Application Notes for Java Message Service (JMS) Integration Between the Avaya Event Processor and the IBM WebSphere Application Server - Issue 1.

Transcription

1 Avaya Solution & Interoperability Test Lab Application Notes for Java Message Service (JMS) Integration Between the Avaya Event Processor and the IBM WebSphere Application Server - Issue 1.0 Abstract These Application Notes describe a sample configuration for Java Message Service (JMS) integration between the Avaya Event Processor (EP) and the IBM WebSphere Application Server (WAS). The IBM WAS implements a JMS provider, which makes available JMS connection factories and destinations (queues and topics) for JMS-capable applications to use in exchanging JMS messages. In the context of the JMS architecture, the Avaya EP is a JMScapable application that accesses JMS destinations on the IBM WAS to exchange data with other JMS-capable applications. 1 of 35

2 1. Introduction These Application Notes describe a sample configuration for Java Message Service (JMS) integration between the Avaya Event Processor (EP) and the IBM WebSphere Application Server (WAS). The JMS API is an enterprise messaging tool that allows Java 2 Enterprise Edition (J2EE) applications to exchange data reliably and asynchronously. JMS-capable applications can be created to integrate heterogeneous enterprise applications and systems in a loosely-coupled manner, allowing the applications and systems to exchange data independent of the respective native data formats. The IBM WAS implements a JMS s provider, which makes available JMS connection factories and destinations (queues and topics) for JMS-capable applications to use in exchanging JMS messages. In the context of the JMS architecture, the Avaya EP is a JMS-capable application that accesses JMS destinations on the IBM WAS. Upon reception of a JMS message from a JMS destination on the IBM WAS, the Avaya EP can extract relevant data from the message and insert the data into one or more Avaya EP Streams. Similarly, the Avaya EP can extract data from one or more Avaya EP Streams and send the data in a JMS message to another JMS destination on the IBM WAS. 2. Configuration The sample configuration used in these Application Notes is shown in Figure / Avaya Event Processor Server IBM WebSphere Application Server JMS-capable Application/System Figure 1: Configuration In the sample configuration, the IBM WAS is installed on a Microsoft Windows 2003 Server, and the Avaya EP is installed on a Red Hat Enterprise Linux ES 4.0 server. JMS-capable applications and the Avaya EP exchange data by sending and receiving JMS messages to and from one or more specified JMS destinations configured on the IBM WAS. In these Application Notes, JMS destination queues are configured on the IBM WAS; consult the IBM WAS documentation [3] for guidance on configuring JMS destination topics. 2 of 35

3 3. Equipment and Software Validated The following equipment and software were used for the sample configuration provided: Equipment & Software Version Avaya Event Processor running on Red Hat Enterprise _GA_26 Linux ES Release 4.0 (Nahant Update 5) Server IBM WebSphere Application Server Network Deployment Table 1: Equipment/Software List 4. Avaya Event Processor 4.1. Event Processing Language This section describes the Event Processing Language (EPL) statements for configuring the Avaya EP to receive and send JMS messages from and to JMS destinations on the IBM WAS. The EPL statements may be executed dynamically on a running Avaya EP server instance, or saved in EPL files. EPL files are saved in the [Avaya EP installation directory]/eplserver/[avaya EP server instance]/engine/epl directory, and are automatically executed when the Avaya EP server instance is started. Consult the Avaya EP documentation [1][2] for further details on EPL structure and syntax, and EPL files. Step 1. Create a JMS Pool in the Avaya EP that accesses a JMS connection factory on the IBM WAS, using the following parameters: initialcontextfactory com.ibm.websphere.naming.wsninitialcontextfactory jndiurl corbaloc:iiop:<ip address, hostname, or FQDN of IBM WAS>:<bootstrap address port obtained in Section 5.1 Steps 3-4> JMSFactory name of JMS connection factory configured on the IBM WAS in Section 5.3 Steps 3-7. The sample EPL statement below creates a Resource of type JMS_POOL named MyJMSPool that accesses a JMS connection factory named jms/connfactory1 on the IBM WAS. CREATE RESOURCE MyJMSPool JMS_POOL { JMSFactory 'jms/connfactory1', acknowledgemode 'AUTO_ACKNOWLEDGE', initialcontextfactory 'com.ibm.websphere.naming.wsninitialcontextfactory', jndiurl 'corbaloc:iiop: :2810', password '', poolsize 10, resourcename 'MyJMSPool', transacted false, username '' } 3 of 35

4 2. Create a Stream in the Avaya EP into which data extracted from received JMS messages can be inserted. The sample EPL statement below creates a Stream named MyJMSReceiveStream, where each data record in the Stream will consist of two fields, ITEM and PRICE. Note that each field name must match a name-value pair in the received JMS message. CREATE STREAM system:myjmsreceivestream TYPE { ITEM String, PRICE Double } 3. Create a Stream Provider in the Avaya EP that receives JMS messages from a JMS destination on the IBM WAS, and inserts the data in the JMS messages into the Stream configured in Step 2. Configure the Stream Provider with the built-in type JMS_PROVIDER and the following parameters: jmsdestination name of JMS destination queue or topic configured on the IBM WAS in Section 5.3 Steps 8-12 from which the Avaya EP will receive JMS messages. jmsdomain QUEUE or TOPIC. jmsmessagetype MapMessage. poolname name of JMS Pool configured in Step 1. STREAM name of Stream configured in Step 2. The sample EPL statement below creates a Stream Provider of type JMS_PROVIDER named MyJMSReceiveStreamProvider that receives JMS messages of type MapMessage from the JMS queue jms/queue1 on the IBM WAS, and inserts the data in the JMS messages into the MyJMSReceiveStream Stream. CREATE STREAMPROVIDER system:myjmsreceivestreamprovider JMS_PROVIDER ON STREAM system:myjmsreceivestream { importallheaders true, jmsdestination 'jms/queue1', jmsdomain 'QUEUE', jmsmessagetype 'MapMessage', poolname 'MyJMSPool', selector '', useheadertimestamp true } 4. Create a Stream in the Avaya EP from which data can be extracted and sent in JMS messages. The sample EPL statement below creates a Stream named MyJMSSendStream, where each data record in the Stream will consist of two fields, ITEM and PRICE. CREATE STREAM system:myjmssendstream TYPE { ITEM String, PRICE Double } 4 of 35

5 5. Create a Stream Listener that listens on the Stream configured in Step 4 and sends the data in the Stream to another JMS destination on the IBM WAS. Configure the Stream Listener with the built-in type JMS_LISTENER and the following parameters: jmsdestination name of JMS destination queue or topic configured on the IBM WAS in Section 5.3 Step 13 to which the Avaya EP will send JMS messages. jmsdomain QUEUE or TOPIC. jmsmessagetype MapMessage. poolname name of JMS Pool configured in Step 1. STREAM name of Stream configured in Step 4. The sample EPL statement below creates a Stream Listener of type JMS_LISTENER named MyJMSSendStreamListener that extracts data from the MyJMSSendStream Stream and sends the data in JMS messages of type MapMessage to the JMS queue jms/queue2 on the IBM WAS. CREATE STREAMLISTENER system:myjmssendstreamlistener JMS_LISTENER ON STREAM system:myjmssendstream { exportallheaders false, jmsdestination 'jms/queue2', jmsdomain 'QUEUE', jmsmessagetype 'MapMessage', poolname 'MyJMSPool', useheadertimestamp true } 4.2. JAR Files and Runtime Classpath This section lists the JAR files that must be included in the Avaya EP server classpath at runtime. The JAR files must precede the ep-classpath.jar JAR file in the runtime classpath. Specifically, these JAR files must precede any Sun Microsystems j2ee.jar (or similar) JAR files in the runtime classpath. The ep-classpath.jar JAR file provided in the Avaya EP server contains a manifest.mf file that includes j2ee.jar in the classpath. Step 1. Add the following Avaya EP JAR file to the [Avaya EP installation directory]/lib directory: ep_jms_patch_1.0.0.jar Note: Contact Avaya to obtain this JAR file or the equivalent. 5 of 35

6 2. Add the following IBM WAS JAR files to the [Avaya EP installation directory]/lib/third_party directory: sibc.jms.jar sibc.jndi.jar sibc.orb.jar Note: In these Application Notes, a directory named IBMWAS was created in the [Avaya EP installation directory]/lib/third_party directory and the above JAR files were placed in the [Avaya EP installation directory]/lib/third_party/ibmwas directory. 3. In the [Avaya EP installation directory]/bin directory, modify the setenv.sh file, or copy the setenv.sh file to another name, and modify as follows. The modifications are in bold below. IBMWAS_CP=$LIB/ep_jms_patch_1.0.0.jar IBMWAS_CP=$IBMWAS_CP:$LIB/third_party/IBMWAS/sibc.jms.jar IBMWAS_CP=$IBMWAS_CP:$LIB/third_party/IBMWAS/sibc.jndi.jar IBMWAS_CP=$IBMWAS_CP:$LIB/third_party/IBMWAS/sibc.orb.jar export IBMWAS_CP BASE_CP=$CONF_CP:$TOOLS_CP:$EP_CP:$IBMWAS_CP:$LIB/ep-classpath.jar export BASE_CP Note: For the Avaya EP development version running on a Microsoft Windows server, the equivalent file is setenv.bat and the equivalent modifications are in bold below. SET IBMWAS_CP=%LIB%/ep_jms_patch_1.0.0.jar SET IBMWAS_CP=%IBMWAS_CP%;%LIB%/third_party/IBMWAS/sibc.jms.jar SET IBMWAS_CP=%IBMWAS_CP%;%LIB%/third_party/IBMWAS/sibc.jndi.jar SET IBMWAS_CP=%IBMWAS_CP%;%LIB%/third_party/IBMWAS/sibc.orb.jar export IBMWAS_CP BASE_CP=%CONF_CP%;%TOOLS_CP%;%EP_CP%;%IBMWAS_CP%;%LIB%/ep-classpath.jar 6 of 35

7 4.3. Startup Script The [Avaya EP installation directory]/eplserver/[avaya EP server instance]/bin/eplserver.sh file (or eplserver.bat for the Avaya EP development version running on a Microsoft Windows server) is a script for starting an Avaya EP server instance. This section describes the runtime parameters that must be added to the eplserver.sh (or eplserver.bat) file. Step 1. Include the runtime parameter com.ibm.corba.orbinit=com.ibm.ws.sib.client.orb in the eplserver.sh (or eplserver.bat ) file. For example: Linux: "$JAVA_HOME/bin/java" -Dcom.ibm.CORBA.ORBInit=com.ibm.ws.sib.client.ORB -cp "$CP" -server -Xms256m -Xmx512m -Davaya.coreservices=$EP_CS_FLAG - Djava.security.auth.login.config=conf/login.conf - DEVENT_PROCESSOR_LICENSE_DIRECTORY="$EVENT_PROCESSOR_LICENSE_DIRECTORY" - Djava.util.logging.config.file=conf/logging.properties - DLOG_FILE=logs/web.log com.ispheres.epm.server.server -webserver -soap engine $1 $2 $3 $4 $5 $6 $7 $9 Windows: "%JAVA_HOME%\bin\java.exe" -Dcom.ibm.CORBA.ORBInit=com.ibm.ws.sib.client.ORB -cp "%CP%" -server -Xms256m -Xmx512m -Davaya.coreservices=%EP_CS_FLAG% - Djava.security.auth.login.config=conf/login.conf - DEVENT_PROCESSOR_LICENSE_DIRECTORY="%EVENT_PROCESSOR_LICENSE_DIRECTORY%" - Djava.util.logging.config.file=conf/logging.properties - DLOG_FILE=logs/web.log com.ispheres.epm.server.server -webserver -soap engine %1 %2 %3 %4 %5 %6 %7 %9 2. If a copied and renamed setenv.sh (or setenv.bat ) file was used in Section 4.2 Step 3, then modify the default environment setting in the eplserver.sh (or eplserver.bat ) file with the name of the renamed file. For example: Linux:. /usr/local/ep/bin/setenvibmwas.sh Windows: call C:\Program Files\Avaya\Event Processor\bin\setEnvIBMWAS.bat 3. If the Avaya EP is unable to resolve the hostname or FQDN of the IBM WAS, then add an entry with the IP address, hostname, and FQDN of the IBM WAS to the /etc/hosts (Linux) or C:\WINDOWS\system32\drivers\etc\hosts (Windows) file on the Avaya EP server. 7 of 35

8 5. IBM WebSphere Application Server This section describes the steps for configuring JMS resources, including JMS connection factories and queues, on the IBM WAS Server Ports Step 1. Start the appropriate server instance on the IBM WAS. In these Application Notes, the default server instance is utilized. After the server instance is started, launch the Integrated Solutions Console (Administrative Console) and log in. 2. In the left pane of the Integrated Solutions Console, select Servers Application servers. In the Application servers page, click on the name of the server instance. 8 of 35

9 3. In the server page, scroll down and under Communications, click on Ports. 9 of 35

10 4. Note the Port numbers for BOOTSTRAP ADDRESS and SIB ENDPOINT ADDRESS. 10 of 35

11 5.2. Bus Resources Step 1. In the left pane of the Integrated Solutions Console, select Service integration Buses. In the Buses page, click on New. 2. In the Create a new bus page, enter a descriptive name, and click on Next. 11 of 35

12 3. In the Confirm create of new bus page, click on Finish. 4. In the Buses page, click on Save, and then click on the Bus ( Bus1 below) created in Steps of 35

13 5. In the Bus page, under Topology, click on Bus members. 6. In the Bus members page, click on Add. 13 of 35

14 7. In the Select server, cluster or WebSphere MQ server page, select the Server radio button and the appropriate application server instance in the pull-down menu, and click on Next. 8. In the Select the type of message store page, click on Next. 14 of 35

15 9. In the Provide the message store properties page, click on Next. 15 of 35

16 10. In the Confirm the addition of a new bus member page, click on Finish. 11. In Bus members page, click on Save, and then click on the bus ( Bus1 in Buses > Bus1 > Bus members below) created in Steps of 35

17 12. In the Bus page, under Destination resources, click on Destinations. 13. In the Destinations page, click on New. 17 of 35

18 14. In the Create new destination page, select the Queue radio button, and click on Next. 15. In the Set queue attributes page, enter a descriptive Identifier, and click on Next. 18 of 35

19 16. In the Assign the queue to a bus member page, select the bus member configured in Steps 6 11, and click on Next. 17. In the Confirm queue creation page, click on Finish. 19 of 35

20 18. In the Destinations page, click on Save. 19. Repeat Steps to create another bus destination named DestQueue2. Two bus destinations are needed for the two JMS queues configured in Section 5.3 Steps In the left pane of the Integrated Solutions Console, select Service integration Buses. In the Buses page, click on the Bus created in Steps of 35

21 21. Scroll down and under Additional Properties, click on Security. 22. Uncheck the Enable bus security checkbox, select the Allow the use of all defined transport channel chains radio button, and click on OK. 21 of 35

22 23. In the Bus page, click on Save. 22 of 35

23 5.3. JMS Resources Step 1. In the left pane of the Integrated Solutions Console, select Resouces JMS JMS providers. In the JMS providers page, click on the Default messaging provider for the desired scope (cell manager, cell, node, server, etc.). Note that the scope options may differ depending on the type of WAS deployment, so consult the IBM WAS documentation [3] for further details. 23 of 35

24 2. In the Default messaging provider page, under Additional Properties, click on Connection factories. 3. In the Connection factories page, click on New. 24 of 35

25 4. In the New JMS connection factory page, enter a descriptive Name and JNDI name, and select the bus created in Section 5.2 Steps 1 4 for Bus name. 25 of 35

26 5. Scroll down and in the Provider endpoints box, enter <IP address of IBM WAS server>:<sib endpoint address port obtained in Section 5.1 Steps 3-4>:BootstrapBasicMessaging. 26 of 35

27 6. Scroll down to the bottom of the page and click on OK. 27 of 35

28 7. In the Connection factories page, click on Save, and then click on Default messaging provider (in JMS providers > Default messaging provider > Connection factories below). 28 of 35

29 8. In the Default messaging provider page, click on Queues. 9. In the Queues page, click on New. 29 of 35

30 10. In the New JMS queue page, enter a descriptive Name and JNDI name. 11. Scroll down in the New JMS queue page, select the bus created in Section 5.2 Steps 1 4 for Bus name, and select the bus destination configured in Section 5.2 Steps for Queue name. Click on OK. 30 of 35

31 12. In the Queues page, click on Save. In these Application Notes, the Avaya EP is a consumer of JMS messages from the JMS queue created in Steps 8 11, i.e., the Avaya EP will receive JMS messages from this JMS queue. 13. Repeat Steps 8 12 to create another JMS queue named Queue2 (with JNDI name jms/queue2. In these Application Notes, the Avaya EP is a producer of JMS messages to this JMS queue, i.e., the Avaya EP will send JMS messages to this JMS queue. 31 of 35

32 14. In the left pane of the Integrated Solutions Console, select Servers Application servers. In the Application servers page, select the application server instance and click on Start. 32 of 35

33 6. Verification Steps The following steps may be used to verify the configuration: Configure a JMS-capable application to send JMS messages to the JMS queue (e.g., jms/queue1 ) on the IBM WAS from which the Avaya EPL application receives JMS messages. From the JMS-capable application, send a JMS message to that JMS queue and verify that the Avaya EPL application receives the message and inserts the data into the appropriate Stream (e.g., MyJMSReceiveStream ). Configure the JMS-capable application to receive JMS messages from another JMS queue (e.g., jms/queue2 ) on the IBM WAS to which the Avaya EPL application sends JMS messages. Insert data into the appropriate Stream (e.g., MyJMSSendStream ) and verify that the JMS-capable application receives a JMS message from that JMS queue containing the inserted data. Notes: 1. The Avaya EP Console web application may be used to view data in Streams and insert data into Streams. 2. If an external JMS-capable application is not available, configure the Avaya EPL application to send and receive JMS messages to and from the same JMS queue (i.e., loopback). For example, set the jmsdestination parameters in the Stream Provider and Stream Listener configurations in Section 4.1 to the same JMS destination (e.g., jms/queue1 ), and create the Event Definitions below in the Avaya EP to verify the configuration. CREATE EVENT DEFINITION system:sendevent ON CLOCK.SCHEDULE(NOW(), TIME(0,0,30)) THEN MyJMSSendStream.INSERT( ITEM= Shades, PRICE=20.95 ) CREATE EVENT DEFINITION system:receiveevent ON MyJMSReceiveStream THEN PRINT( Got input: ITEM= + MyJMSReceiveStream.ITEM + PRICE= + MyJMSReceiveStream.PRICE ) The SendEvent Event Definition inserts an event (data record) into the MyJMSSendStream Stream every thirty seconds, and the ReceiveEvent Event Definition prints the contents of each received event (data record) in the MyJMSReceiveStream Stream. If the Stream Listener and Stream Provider in Section 4.1 are both configured to access the same JMS destination, then the following should be printed approximately every thirty seconds: Got input: ITEM=Shades PRICE= of 35

34 7. Conclusion These Application Notes described a sample configuration for Java Message Service (JMS) integration between the Avaya Event Processor (EP) and the IBM WebSphere Application Server (WAS). The IBM WAS implements a JMS provider, which makes available JMS connection factories and destinations (queues and topics) for JMS-capable applications to use in exchanging JMS messages. In the context of the JMS architecture, the Avaya EP is a JMScapable application that accesses JMS destinations on the IBM WAS to exchange data with other JMS-capable applications. 8. Additional References The following document may be found under the [Avaya EP installation directory]/docs directory on the Avaya EP server. [1] Getting Started with the Avaya Event Processor 2.0 The following document may be obtained from [2] Avaya Event Processor 2.0 User s Guide, November [3] IBM WebSphere Application Server documentation may be obtained from 34 of 35

35 2008 Avaya Inc. All Rights Reserved. Avaya and the Avaya Logo are trademarks of Avaya Inc. All trademarks identified by and are registered trademarks or trademarks, respectively, of Avaya Inc. All other trademarks are the property of their respective owners. The information provided in these Application Notes is subject to change without notice. The configurations, technical data, and recommendations provided in these Application Notes are believed to be accurate and dependable, but are presented without express or implied warranty. Users are responsible for their application of any products specified in these Application Notes. Please any questions or comments pertaining to these Application Notes along with the full title and filename, located in the lower right corner, directly to the Avaya Solution & Interoperability Test Lab at 35 of 35