WebSphere MQ V7 STEW. JMS Setup Lab. October 2008 V2.3

JMS Setup Page 2 of 47

JMS Setup Overview The purpose of this lab is to show an example of a simple JMS Application and the environment required to develop and run a JMS Application. The lab will show how to configure the Administered objects the program requires. Administered objects are used to specify Connection Factories and Destinations outside of the program, allowing JMS Applications to be portable between Messaging Providers. JMS Applications use JNDI to look up the Administered Objects. Note Connection Factories and Destinations can also be hard coded in to a JMS program if you only ever want your JMS Applications to run against the one Messaging Provider and this example will be shown in the JMS API link lab. In this lab you will perform the following: Create Administered Objects using MQ Explorer. A Connection Factory specifying the WMQ v7 details and a Destination specifying a Queue will be created. Set up an environment for developing and running JMS programs using the Java perspective in Eclipse. Walkthrough a JMS sample program that will simply put a message to a queue. Run the JMS sample program using the Eclipse console to provide input and view the results in MQ Explorer. Prerequisites The lab assumes that the Queue Manager WMQ7 created in the Install lab will be used for this lab. You should be logged on with the same id as per the Install lab. The c:\student directory The lab instructions assume that the materials made available in the file wmq7.driver2.student.zip have been unzipped to the c: drive into a directory structure beginning with c:\student. JMS Setup Page 3 of 47

Create Administered Objects using MQ Explorer 1. Create a directory called C:\JMS for the JNDI Namespace location. (The name of the directory is not important but this lab assumes C:\JMS). 2. Open Websphere MQ Explorer and highlight JMS Administered Objects as shown below. JMS Setup Page 4 of 47

Create the Initial Context 1. Right Click JMS Administered Objects and select Add Initial Context 2. 3. On the Connection details screen, select File System and type (or navigate to using Browse ) the directory C:\JMS in the Bindings directory field and then click Next. 4. JMS Setup Page 5 of 47

5. On the User preferences screen, enter the Context nickname Context1. Note this can be a name of your choice but for this lab we will use Context1. This name will not be used elsewhere. Select Connect immediately on finish and Automatically reconnect to context on startup and click Finish. 6. 7. The newly created initial context is displayed in the list. 8. JMS Setup Page 6 of 47

Create a connection factory for MQ 1. Expand the Context name you created and select Connection Factories. Right click Connection Factories, select New, Connection Factory. 2. 3. Enter the name CF1. Note this can be any name of your choice but for this lab we will use CF1. This will be required when running the program so please note this down. Accept Websphere MQ as the provider and click Next. JMS Setup Page 7 of 47

4. 5. On the next screen, accept the Type as Connection Factory and leave Support XA transactions unchecked. Click Next. 6. On the Next screen, accept Bindings as the Transport given we will run the JMS Application on the same machine as the Queue Manager. Click Next. JMS Setup Page 8 of 47

7. Click Next again leaving Create with attributes like an existing connection factory unchecked. JMS Setup Page 9 of 47

8. Select General on the left hand menu for the Provider version, select 7. This represents WMQ v7. 9. Select Connection on the left-hand menu, use the Select button for Base queue manager. JMS Setup Page 10 of 47

10. 11. Select the newly created Queue Manager WMQ7 and press OK 12. JMS Setup Page 11 of 47

13. Click Finish. 14. 15. Dismiss the confirmation box 16. Observe the Connection Factory now appears in the list. JMS Setup Page 12 of 47

JMS Setup Page 13 of 47

Create a Destination for the JMS Application to put a message to. 1. Select Destinations. 2. Right click Destinations and click New -> Destination 3. JMS Setup Page 14 of 47

4. Enter the name JMS1. Note this can be any name of your choice but for this lab we will use JMS1. This will be required when running the program so please note this down. Leave the Type as Queue and ensure Start wizard to create a matching MQ Queue is checked. This will create a corresponding WMQ Queue. The Queue that you create will be used to verify messages are successfully put to it. Click Next. JMS Setup Page 15 of 47

5. Accept the defaults on this next screen and click Next. 6. On the change properties screen we set some MQ properties of the destination. Select WMQ7 as the Queue Manager and define a Queue with the same name as the Destination. Note the Queue name can be any name of your choice but for this lab we will use JMS1. This will be created as part of the upcoming wizard. Click Finish. JMS Setup Page 16 of 47

7. Dismiss the confirmation prompt 8. The create Queue wizard will now commence. Click Next. JMS Setup Page 17 of 47

9. Accept the default Local Queue and click Next. JMS Setup Page 18 of 47

10. Accept the default attributes for the queue and click Finish.. JMS Setup Page 19 of 47

11. Dismiss the confirmation prompt. 12. Use MQ Explorer to confirm the local queue JMS1 has been created. JMS Setup Page 20 of 47

Set up an environment for developing and running JMS programs using the Java perspective in Eclipse. We set some options required for this and future labs. Please feel free to investigate other options that are available. 1. From the MQ Explorer toolbar, select Window -> Preferences. 2. 3. On the left hand menu, select General -> Perspectives. In Open a new perspective, check In a new window. Click Apply. JMS Setup Page 21 of 47

4. 5. Whilst in Preferences, now Select Java -> Build Path and check Project. Click OK JMS Setup Page 22 of 47

6. From the MQ Explorer toolbar, select Window -> Open Perspective, Other JMS Setup Page 23 of 47

7. Select Java and click OK. 8. The Java Perspective opens JMS Setup Page 24 of 47

9. Right click anywhere in the Package Explorer white space and select New -> Java Project. 10. Call the Project name JMS Lab. Accept the defaults and click Next. JMS Setup Page 25 of 47

11. Select the Libraries tab and click on Add External JARs. JMS Setup Page 26 of 47

12. 13. Navigate to D:\Applications\IBM\Websphere MQ\Java\lib. Select all *.jar files and click Open. Whilst only a subset of jar files are required for this lab, more will be required for the second JMS lab. JMS Setup Page 27 of 47

14. Click Finish. JMS Setup Page 28 of 47

15. Expand JMS Lab and the view in Package Explorer should now look like the following: JMS Setup Page 29 of 47

16. Right click on JMS Lab and select Import. 17. 18. Expand General and select File System. Then click Next. JMS Setup Page 30 of 47

19. Navigate to D:\STEW\WMQv7\Labs\Lab_JMSSetup and click OK. JMS Setup Page 31 of 47

20. 21. Check Lab_JMSSetup and on the right hand options, ensure that Sender.java is checked in the left hand options and then click Finish. JMS Setup Page 32 of 47

22. Expand the folders under JMS Lab and the Project tree in Package Explorer should now look like this 23. Right click on Sender.java and select Run As -> Open Run Dialog. JMS Setup Page 33 of 47

24. Right click on Java Application and select New. JMS Setup Page 34 of 47

25. Select the Arguments tab. In VM arguments, enter the following ensuring there is a space (not a carriage return or newline ) between the 2 Djava statements: -Djava.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory -Djava.naming.provider.url=file:C:/JMS/ Click Apply. The box below contains the required string on a single line. -Djava.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory -Djava.naming.provider.url=file:C:/JMS/ JMS Setup Page 35 of 47

26. Click Close. The environment is now prepared for running the JMS Application called Sender. JMS Setup Page 36 of 47

Walkthrough the Sender.java program 1. Double click Sender.java in Package Explorer to open the source code. 2. 3. The source will be opened in one of the eclipse panes. 4. 5. The pane is likely to be rather too small for viewing the source. Optionally maximize the view so the source code pane (or any other pane) by double clicking on the tab.(doubleclicking the maximised pane will restore the layout). JMS Setup Page 37 of 47

6. JMS Setup Page 38 of 47

Looking at the send method. 1) We initially prompt for the JNDI names of the Administered objects (you will need both the Connection Factory and Destination names you created earlier in the Administered Objects exercise). 2) Next we look up the Administered Objects in JNDI with the names that you supply. JNDI is accessed by instantiating an InitialContext object. The Administered Objects are retrieved by calling the lookup(string) method, passing in the name of the object to be retrieved. Note that the lookup(string) method returns Object, so a typecast must be performed on the returned object. 3) Next we create the JMS objects we need to send messages. Note that we don't directly instantiate these objects using new. All of the objects are created by calling a method on another object. First, we use the ConnectionFactory to create a Connection. We then use that Connection to create a Session. The Session is not transacted (false) and will use automatic acknowledgment (Session.AUTO_ACKNOWLEDGE). Then we create the Sender to send messages to the Destination we retrieved from JNDI. 4) We then loop building a TextMessage from the entered text and use the MessageProducer to send the message. 5) Once the loop exits, we close the Connection. Closing the Connection automatically closes the Session and MessageProducer. JMS Setup Page 39 of 47

JMS Setup Page 40 of 47

Run the JMS Application 1. Firstly we need a console to provide input in to the program. Inside MQ Explorer click on Window -> Show View -> Console 2. To run the program, highlight the Sender.java program, right mouse-click and choose Run As Java Application (or press F11). JMS Setup Page 41 of 47

JMS Setup Page 42 of 47

3. In order to interact with the program, click on the Console tab then click within the Console view. 4. 5. Enter the Connection Factory name you created earlier. CF1 6. Enter the Destination name you created earlier. JMS1 7. Enter a message which will be put to the WMQ queue. 8. Type quit to end or alternatively you can send more messages. JMS Setup Page 43 of 47

9. 10. To verify the messages were put to your queue (this is the queue JMS1 created when creating the Destination) use MQ Explorer. (The MQ Explorer perspective should still be open in another window. Otherwise, choose it from selecting Window -> Open Perspective -> Other.) 11. 12. You should see the messages you put. Select one of the messages, right mouse click and choose properties. JMS Setup Page 44 of 47

13. 14. In the Data tab you can see the message data, in particular the text you typed in the JMS Message. 15. 16. In the Named properties tab you will see some properties that have been set by JMS. This is an illustration of the message properties that can be accessed by the new WMQ message properties APIs. JMS Setup Page 45 of 47

17. You have now verified you can put a message to a queue using JMS. Both the MQ Explorer and the Java perspective can now be closed. JMS Setup Page 46 of 47

Summary In this lab you have Created Administered Objects using MQ Explorer. Set up an environment for developing and running JMS programs using the Java perspective in Eclipse. Explored JMS code used to put a message to a queue. Ran the JMS sample program and viewed the results in MQ Explorer. This ends the lab. End JMS Setup Page 47 of 47