Developing and running applications that use the Messaging Toolkit

IBMStreams com.ibm.streamsx.messaging Toolkit > com.ibm.streamsx.messaging 5.4.3 > Developing and running applications that use the Messaging Toolkit

To create applications that use the Messaging Toolkit, you must configure either Streams Studio or the SPL compiler to be aware of the location of the toolkit.

Before you begin

  • Install IBM Streams. Configure the product environment variables by entering the following command:
      source product-installation-root-directory/4.0.0.0/bin/streamsprofile.sh
    
  • Install a supported version of WebSphere MQ Client, Apache ActiveMQ and XMS client on the same machine as IBM Streams. WebSphere MQ Server might or might not be on the same machine.

    For Kafka and MQTT, the toolkit ships with a set of required clients, and therefore this configuration is not needed.

    • Apache ActiveMQ
      • The JMSSource and JMSSink operators support Apache ActiveMQ 5.7 and up.
        • The Apache ActiveMQ libraries must be installed on same machine as IBM Streams because the JMSSink and JMSSource operators require the libraries that are installed with IBM Streams. However, the ActiveMQ instance to which a message is sent can be a different machine. You must set the STREAMS_MESSAGING_AMQ_HOME environment variable to the location where Apache ActiveMQ is installed. For example:
            export STREAMS_MESSAGING_AMQ_HOME="/home/streamsuser/ApacheActiveMQ"
          
    • WebSphere MQ Server
      • The JMSSource, JMSSink, XMSSource and XMSSink operators support WebSphere MQ v7.5 and v8.0.
      • The XMSSource and XMSSink operators require that the IBM Message Service Client (XMS) for C/C++ is installed. You must set the XMS_HOME environment variable to the installation location of XMS Client.
      • The JMSSource and JMSSink operators require the WebSphere MQ Client libraries for Java if the messaging provider is WebSphere MQ.
        • The WebSphere MQ Client libraries must be installed on the hosts where the JMS operators can be run. You must set the STREAMS_MESSAGING_WMQ_HOME environment variable to the location where WebSphere MQ is installed. For example:
            export STREAMS_MESSAGING_WMQ_HOME="/opt/mqm"
          

About this task

After the location of the toolkit is communicated to the compiler, the SPL artifacts that are specified in the toolkit can be used by an application. The application can include a use directive to bring the necessary namespaces into scope. Alternatively, you can fully qualify the operators that are provided by toolkit with their namespaces as prefixes.

Procedure

  1. Review the list of restrictions for the IBM Streams specialized toolkits in the product documentation. For example, the XMSSource and XMSSink operators are supported on x86_64 systems.
  2. Verify that the appropriate environment variables are set for the messaging systems that you use.
    • If you use JMSSink or JMSSource operators to connect to WebSphere MQ or Apache ActiveMQ systems, set STREAMS_MESSAGING_WMQ_HOME or STREAMS_MESSAGING_AMQ_HOME respectively.
    • If you use XMSSink or XMSSource operators to connect to WebSphere MQ messaging systems, set XMS_HOME, MQ_HOME, and LD_LIBRARY_PATH.
  3. Configure the SPL compiler to find the toolkit root directory. Use one of the following methods:
    • Set the STREAMS_SPLPATH environment variable to the root directory of a toolkit or multiple toolkits (with : as a separator). For example:
        export STREAMS_SPLPATH=$STREAMS_INSTALL/toolkits/com.ibm.streamsx.messaging
      
    • Specify the -t or --spl-path command parameter when you run the sc command. For example:
        sc -t $STREAMS_INSTALL/toolkits/com.ibm.streamsx.messaging -M MyMain
      
      where MyMain is the name of the SPL main composite. Note: These command parameters override the STREAMS_SPLPATH environment variable.
    • Add the toolkit location in IBM Streams Studio.
  4. Develop your application. To avoid the need to fully qualify the operators, add a use directive in your application.
    • For example, you can add the following clause in your SPL source file:
        use com.ibm.streamsx.messaging.jms::*;
        use com.ibm.streamsx.messaging.mqtt::*;
        use com.ibm.streamsx.messaging.xms::*;
        use com.ibm.streamsx.messaging.kafka::*;
      
      You can also specify a use clause for individual operators by replacing the asterisk (*) with the operator name. For example:
        use com.ibm.streamsx.messaging.jms::JMSSink;
        use com.ibm.streamsx.messaging.mqtt::MQTTSink; 
        use com.ibm.streamsx.messaging.xms::XMSSource;
        use com.ibm.streamsx.messaging.kafka::KafkaConsumer;
      
  5. Build your application. You can use the sc command or Streams Studio.
  6. Start the IBM Streams instance.
  7. Run the application. You can submit the application as a job by using the streamtool submitjob command or by using Streams Studio.