Introduction

Extended Messaging enhances the basic messaging that's available within WebSphere® Application Server by integrating it with the Enterprise JavaBeans (EJB) component model. The Extended Messaging Service (EMS) function is available in WebSphere Application Server Enterprise, Version 5. Tooling support is available in WebSphere Studio Application Developer, Integrated Edition, Version 5, making the development of complex messaging applications on top of EJBs easy and fast by generating the actual code to do the message sending, receiving and reply handling for you.

This tutorial will guide you through the building of a simple sender-receiver EMS application, and will help you:

• Understand basic EMS concepts.
• Use the various WebSphere Studio Application Developer, Integrated Edition, Version 5 wizards to create EMS applications.
• Configure, run and test an EMS application using the Enterprise unit test environment of WebSphere Studio Application Developer Integrated Edition.

This tutorial is intended for EJB developers that want to experiment with messaging, or messaging developers that want to work with EJBs, and assumes a basic understanding of EJB 2.0 concepts, particularly with regard to Message Driven Beans and the EJB support in WebSphere Studio Application Developer. To follow the instructions in the tutorial, you will need WebSphere Studio Application Developer, Integrated Edition, Version 5 (hereafter called Application Developer).

Back to top

Extended Messaging Service overview

EMS provides a simple programming model, essentially the EJB programming model, for handling incoming and outgoing messages, sending replies, and correlating responses. EMS is built on top of Java^TM Messaging Service (JMS). It encourages the separation of the business logic from the messaging logic through the use of two primary simple messaging patterns: one-way and request-reply. These patterns may be combined to create complex messaging applications and are supported by two types of message beans: sender and receiver beans:

• A sender bean is a stateless session EJB which contains methods for sending messages and receiving responses. It typically converts given parameters from a send to a JMS message, and then converts the response message back to the expected return format and exception types. A sender bean uses a resource called an output port to represent the transport configuration.
• Receiver beans are either asynchronous or synchronous:
  • The asynchronous receiver bean, based on a Message Driven Bean, is invoked by a listener service upon receipt of a message. The receiver bean unpacks the message and uses its content to invoke a method on a target business logic EJB and, optionally, to send back the return value as a reply message.
  • The synchronous receiver bean, also known as an Application Callable Receiver Bean, is based on a stateless session EJB and contains methods to receive data and send replies. There is no listener for this bean and, as the name suggests, the application needs to call the relevant methods on the receiver bean. Synchronous receiver beans use an input port to represent the transport configuration.

For more information on extended messaging concepts, see Resources.

Back to top

Sample application

Let's look at a very simple EMS application to see how this all works.

Suppose we have an EJB, called ShopBean, that contains logic for selling books and CDs. It contains two methods, sellBook(title,author,ISBN) and sellCD(title,author), which query and update databases and then return the price of the respective items. We want to invoke the ShopBean EJB upon receipt of a message. Why? Mainly to get the benefits of messaging: loosely coupled systems along with asynchronicity. Using EMS, we will invoke one of the ShopBean methods from a message-driven receiver bean without having to make any modifications to ShopBean. The receiver bean will be generated by the tooling.

Also using the tooling, we will construct a sender that produces the messages that the receiver expects. The client will be able to invoke methods on the sender bean, possibly unaware that messaging is even being used to trigger the processing. In this context, the client can be any EJB client: a servlet, a Java application or another EJB.

When buying a book, we order the book and receive a correlator in return. We will retrieve the reply, namely the price, at a later point. This mode of interaction, known as "send with deferred response", illustrates the loose coupling of messaging operations that we get with EMS.

The next section outlines the steps to create the sample EMS application. As an alternative, you may download the application rather than build it from scratch. If you choose to download the application, proceed to the section on Configuring, running and testing the EMS application.

Back to top

Building the EMS application

The EMS sample application, emsSample.ear, will contain two EJB projects:

• Receiver: contains the application EJB ShopBean, and the EMS bean Receiver, generated by the tooling.
• Sender: contains the tooling-generated EJB Sender.

Therefore, to build the EMS application you will need to:

1. Create the application EJB
2. Create the receiver bean
3. Create the sender bean.

Steps to accomplish each of these tasks are outlined in the following sections.

A. Create the application EJB

1. Launch Application Developer.
   
   In the next steps, you will create an EJB project.
   
   
2. Select Window => Open Perspective => J2EE to enter the J2EE perspective. If J2EE is not one of the options listed, select Other => J2EE.
3. Select File => New => EJB => EJB Project => Create EJB 2.0 project.
4. Enter the following values in the dialog (Figure 2):
   • Project name: Receiver
   • Enterprise application project: New
   • New project name: emsSample
   Select Finish.
   Figure 2. Create an EJB project
   
   
   In the next steps, you will create the EJB application ShopBean. For simplicity, the application EJB will be in the same EJB project as the receiver bean.
   
   
5. Select File => New => EJB => Enterprise Bean.
6. Select Receiver for the EJB project, then select Next.
7. Enter the following values in the dialog (Figure 3):
   • EJB 2.0 type: Session bean
   • Bean name: ShopBean
   • Default package: ems.
   Select Next, then Finish.
   Figure 3. Create the target EJB
   
   The application EJB will contain the business logic of the application, and will typically be made up of queries and updates to various databases. For the purposes of this example, the business methods will be set up to return constant values.
   
   
8. Edit the ShopBeanBean.java file to add the methods, as follows:
   

   public String sellBook(String title, String author, String ISBN) { // Do something useful here return "J20" } public String sellCD(String title, String author) { // Do something useful here return "J15" }

   
   
9. In the Outline view in Application Developer (Figure 4), select both the sellBook and sellCD methods together, right click and select Enterprise Bean => Promote to remote interface.
10. Save these changes by selecting File => Save All.
    Figure 4. Add to remote interface
    
    

B. Create the receiver bean

In the following steps, you will create a receiver bean by defining the attributes the bean will be based on, and by selecting the method it will invoke on receipt of a message.

1. In the J2EE Hierarchy view in Application Developer, expand the EJBProject group.
2. Right click on Receiver, then select Extended Messaging => Create Receiver Bean from the pop-up window.
3. Click on the Create Receiver button. This will start the Create an Enterprise Bean wizard (Figure 5).
4. Enter the following values in the dialog:
   • Bean name: Receiver
   • Default package: ems.
   Select Next.
   Figure 5. Create receiver EJB
   
   
5. Enter the following values in the next dialog:
   • Destination type: Queue
   • Listener port name: emsLPort
   Select Finish.
6. Returning to the wizard (Figure 6), enter the following values:
   • Reply information: Send reply
   • Message format identifier: BOOK
   Select Finish.
   Figure 6. Create receiver bean
   
   The Message format identifier is used to associate the sending and the receiving ends with each other, so it's important that both the sender and receiver beans use the same identifier.
   
   
7. Select Next.
8. In the Application EJB dialog (Figure 7), you need to choose the method that the receiver bean will invoke. Enter or select the following values:
   • Select Call method on the remote or local interface of a target ejb
   • Application EJB Project: Receiver
   • Application EJB: ShopBean
   • Select Remote interface.
   • Application method: sellBook
   • Accept the default values for the EJB Reference Information fields.
   • Select Next.
   
   Figure 7. Select the target for the receiver bean
   
   
9. A summary page displays a description of what will occur when the wizard completes:
   • receiver bean is generated
   • onMessage method is updated to invoke the target method
   • an EJB reference is generated for the receiver bean
   • a WebSphere binding is generated for the target EJB.
   Select Finish.

C. Create the sender bean

In the following steps, you will create a sender bean that produces the type of messages the receiver bean is expecting. Since the mode of interaction being used is "send with deferred response", the sender bean will have one method to send the request and one method to receive the response. The advantage of this mode of interaction is the decoupling of the two messaging operations. The client can call the first method to do the send, then do some other work and retrieve the response later. A correlator is used to link the request with the later response, as is described below.In the next steps, you will create an EJB project.

1. In Application Developer, select File => New => EJB => EJB Project => Create EJB 2.0 project.
2. Enter the following values:
   • Project name: Sender
   • Enterprise application: emsSample.
   Select Finish.
   
   In the next steps, you will create the sender bean.
   
   
3. In the J2EE hierarchy view in Application Developer, expand the EJBProject group.
4. Right click on Sender, then select Extended Messaging => Create Sender Bean.
5. Click on the Create Sender button. This will start the Create Sender Bean wizard (Figure 8).
6. Enter the following values in the next dialog:
   • Bean name: Sender
   • Default package: ems.
7. Select Next, then Finish. You will return to the Create Sender bean wizard.
8. Returning to the wizard, enter the following values:
   • Output port JNDI name: oPort
   • Response information: Deferred response
   • Message format identifier: BOOK
   
   Figure 8. Create sender bean
   
   The Message format identifier is used to associate the sending and the receiving ends with each other, so it is important to be sure that both the sender and receiver bean use the same identifier. The Output port JNDI name is the JNDI name of the resource that will be configured in the runtime environment.
   
   
9. Select Next.
10. In the Send with deferred response dialog (Figure 9), enter the following values:
    • Sending method name: orderBook, and select Add to remote interface
    • Response timeout option: select No timeout
    • Method name: getBookPrice, and select Add to remote interface
    Selecting Add to remote interface promotes the newly generated methods to the remote interfaces of the sender bean.
    Figure 9. Sending methods
    
    In order for the EMS run time to be able to identify which original request is associated with a response, a correlator is returned by the sending method and passed back to the receiving method as the first parameter. The return type of the sending method is a CMMResponseCorrelator object type.
    
    
11. Next, you decide how to define the signature of the method. You can either:
    • Define the method signature explicitly, by typing the parameters, return value and the exceptions for the sending method (the object types to be sent and what you expect back as a response).
    • Define and validate the method signature. This is the same as the previous option, except that you can select the object types (rather than enter them manually) and the wizard validates them for you.
    • Define the sending method signature by selecting the method which will be invoked at the receiving end, if this information is available. This is the easiest option for this example, since we have the required information, and it ensures the message formats expected on either end match.
    Remember that it is critical that the attributes of the sending method (e.g., the number, order, types and return type of the parameters) match precisely the attributes of the target method invoked at the receiving end.
    
    Select Use method signature from the target bean, then Next.
    
    
12. In the Target Receiver Bean method dialog (Figure 10), choose the method that the receiver bean will invoke to construct the signature of the sending method. Enter the following values:
    • Application EJB Project: Receiver
    • Application EJB: ShopBean
    • Application method: select Remote interface, then select sellBook from the drop-down list.
    The dialog displays how the signature of the generated methods is constructed based on your selections.
    Figure 10. Use receiver bean target to get sending methods signature
    
    
13. Select Next, then Finish.

When the wizard completes, the sender bean is generated, including the messaging methods which are also added to the remote interface. A resource reference for the output port and its WebSphere binding are also created.

Troubleshooting

The hints below may help you avoid common errors when following the above steps:

• The wizards described above will display a Summary page listing the actions that the wizards will complete. If any of these are different from what you expect, go back and change your options before completing the wizard. Modiyfing generated code is not recommended.
• Make sure you selected Promote to remote interface. If you did not select this option, you will need to promote the sending methods explicitly to the remote interface.
• Make sure you added the JNDI bindings for the Output port, or the EJB target or listener port for the receiver bean. Otherwise, you will need to edit the EJB project with the Deployment Descriptor editor.

Back to top

Configuring, running and testing an EMS application

To see the Extended Messaging application in action, you will need to:

1. Create a server and server configuration
2. Configure JMS resources and a listener port for the receiver bean
3. Create an output port for the sender bean
4. Install and run the application
5. Test the application using the universal test client.

Steps to accomplish each of these tasks are outlined in the following sections. If you chose to bypass the application building phase above, you will also need to download and setup the application included with this article:

• Download the emsSample.ear file provided.
• Import the EAR into Application Developer, by selecting File => Import => EAR File, using the following values:
  • Project name: emsSample
  • Select the downloaded file.
• Fix the classpath of the EJB projects, Receiver and Sender, by enter the J2EE perspective in Application Developer:
  1. In the J2EE hierarchy view, expand the EJBProject group.
  2. Right click Receiver, and select Properties => Java Build Path => Libraries.
  3. Select Add Variable.
  4. Select WAS_EE_V5, then Expand.
  5. Select lib\cmm.jar, then OK.
  6. Repeat for Sender.
  This process should alleviate any compilation errors that may occur.

A. Create a server and server configuration

With the next steps, you will create and configure the WebSphere Application Server Enterprise Version 5.0 test environment.

1. In Application Developer, select Window => Open perspective => Other => Server.
2. Select File => New => Server => Server and Server Configuration.
3. Enter the following values in the Create a New Server and Server Configuration dialog (Figure 11):
   • Server name: WASEE
   • Folder: Servers
   • Server type: select WebSphere version 5.0 => EE Test Envitronment.
   
   Figure 11. Create a new server
   
   
4. Select Finish. If prompted to create a new Servers folder, select Yes.

B. Configure JMS resources and listener port

With the test environment created, you will now use the server configuration editor to enable the administrative console client, and to create JMS resources and a listener port.

1. In the Server Configuration view of Application Developer, expand the Server Configurations tree. Double-click WASEE to launch the server configuration editor (Figure 12).
2. You will need the administrative console for WebSphere Application Server Enterprise Version 5.0 from Application Developer to create an output port. In the Configuration pane of the server configuration editor, select Enable administration console (Figure 12).
   Figure 12. Enable administration client for the server
   
   Be aware of the other panes available through the tabs at the bottom of the server configuration editor (also shown in Figure 12), particularly for JMS and EJB. These will be used in subsequent steps.

   Since EMS is based on JMS, you need to define the JMS administered objects:

   • connection factory: used by clients to create connections to a provider
   • destinations: used to specify the target of the sent messages, and the source of received messages.

   For this example, then, you will configure the following in the JMS pane:

   • queue connection factory: myQCF
   • two destinations: myQueue (for requests) and myReplyQueue (for responses).
3. Select the JMS tab of the server configuration editor (Figure 12).
4. For this example, you will declare JMS resources at the Node level. Scroll down to the Node Settings section and expand.
5. Next to the WASQueueConnectionFactory section, select Add (Figure 13).
   Figure 13. Configure JMS resources for the node
   
   
6. In the Add WASQueueConnectionFactory dialog (Figure 14), enter the following values:
   • Name: myQCF
   • JNDI Name: ems/myQCF
   • Node: select localhost
   • Server Name: select server1
   Select OK.
   Figure 14. Add a JMS Queue Connection Factory
   
   
7. In the Node Settings section again (Figure 13), scroll down to the WASQueue entries section, and select Add.
8. In the Add WASQueue dialog, enter the following values:
   • Name: myQueue
   • JNDI Name: ems/myQueue
   • Node: localhost
   Select OK.
9. Repeat Step 8 for the reply queue, replacing the following field values:
   • Name: myReplyQueue
   • JNDI Name: ems/myReplyQueue
10. You now need to add the queues to the JMS Server, then activate it. In the JMS tab of the server configuration editor, scroll down to the Server Settings section.
11. Select Add next to the Queue Names field under JMS Server Properties (Figure 15).
12. Add the queue that you just defined, myQueue. Make sure the Initial State field is set to START.
    Figure 15. Add the JMS queue to the server settings
    
    
13. Repeat Step 12 for myReplyQueue.

    Listener ports are used to associate the JMS resources and deployed message-driven beans with the listener service that is handling the incoming messages. The receiver bean is based on a message-driven bean, and hence needs to be associated with a listener port.

14. Select the EJB tab of the server configuration editor in Application Developer (Figure 12), then select Add.
15. In the Add Listener Port dialog (Figure 16), enter the following values:
    • Name: emsLPort
    • Connection Factory JNDI name: ems/myQCF
    • Destination JNDI name: ems/myQueue
    Select OK.
    Figure 16. Add a listener port
    
    
16. Save the server configuration, and close all windows.

    It is not necessary to map the local JNDI names in the J2EE module to the actual JNDI names defined in the server, since we specified JNDI bindings when running the wizards.

C. Create an output port

An output port simplifies how you administer the transport details for a deployed sender bean. The main entries for an output port are the connection factory and one or more destinations. This enables all deployed sender beans associated with the output port to send messages to the destination(s). You can also specify the details of the response (destination and connection factory) and various JMS sending parameters.

1. To create the output port, you first need to start the application server, then open the Administrative Console. To do this from Application Developer, go to the Servers view and select the WASEE server. Right-click on the server name and select Publish => Start (Figure 17).
   Figure 17. Context menu for the WASEE server in the Servers view
   
   
2. Switch to the Console view and wait for the Server1 Open for e-business message to indicate that the server has started. Return to the Servers view (Figure 17).
3. Right-click again on WASEE, and select Run administrative client, which should now be an available option. This launches the Admin Console.
   
   The remaining steps of the output port configuration will be performed using the Admin Console of the Enterprise test environment.
   
   
4. Enter any user ID on the Admin Console and select OK.
5. In the left pane, select Servers => Resources => Extended Messaging Provider (Figure 18).
   Figure 18. Use EMS provider to configure an output port
   
   
6. Select the OutputPort link, then New for the node settings. Enter the following values, as shown in Figure 19:
   • Name: oPort
   • JNDI Name: oPort
   • JMS Connection Factory JNDI Name: select ems/myQCF
   • JMS Destination JNDI Name: select ems/myQueue, then Add
   • JMS Reply Connection Factory JNDI Name: select ems/myQCF
   • JMS Reply Destination JNDI Name: select ems/myReplyQueue
   Select Add. The JNDI name of the output port must be the same as what was specified for JNDI binding when the wizard from the Sender bean was run earlier.
   Figure 19. Output port configuration
   
   
7. Select OK. You have now created the Output Port.
8. At the top of the page, select Save => Save to save the configuration.
9. Select Logout to exit and close the browser.

D. Install and run the application

For this task, you will first generate the deploy code for your application, add it to the server, and then restart the server.

1. In Application Developer, return to the J2EE Hierarchy view from the J2EE perspective, and expand the Enterprise Application group (Figure 20). Right-click on emsSample, and select Generate Deploy Code.
   Figure 20. Generate the deploy code for the enterprise application
   
   
2. From the J2EE Hierachy view again, expand the Server Configuration group. Right-click on WASEE, and select Add => emsSample (Figure 21).
   Figure 21. Add the EMS application to the server
   
   
3. When this completes, you will need to restart the server. From the context menu of the WASEE server in the Servers view (Figure 17), select Restart.

E. Test the application

To test the application, all you really need is any standard EJB client that invokes the methods on the sending bean. Once the sender bean instance is created, you can simply invoke the appropriate messaging methods. The client code below shows an example of how this can be done:

.. 
Sender sender = ..; 
CMMResponseCorrelator corr = sender.orderBook("Java in Nutshell",
"David Flanagan", ""); 
... 
String price = sender.getPrice(corr);

For the purposes of this tutorial, you will use the Universal Test client to test the messaging application.

1. From the Servers view (Figure 17), right-click on WASEE and select Run universal test client.
2. When the test client launches, select JNDI Explorer. Make sure that the output port resource definition, oPort, appears (Figure 22). If it is not listed, the configuration was not properly saved. If necessary, return to Section C to correct.
3. Expand and select ejb => ems => SenderBeanHome (Figure 22).
   Figure 22. JNDI Explorer view of the universal test client
   
   
4. In the EJB reference view, expand EJB References => Sender, and select the create method .
5. In the right panel, select Invoke, then Work with Object.
6. The newly created instance of the Sender object, Sender_1 is now added to the left panel (Figure 23). Expand it and Invoke the orderBook method. In our case, the business method always returns the same hardcoded price, so the values of the arguments which are sent across are irrelevant (you may leave them null).
7. Select Work with Object for the return value. The correlator is added to the list of Object References.
8. Select getPrice, listed under the Sender_1 object. On the list of arguments, select the previously created correlator, then Invoke. The price of the book requested should appear in the Results section.
   Figure 23. EJB reference view of the universal test client
   
   
9. Stop the server and close the client.

Back to top

Conclusion

This tutorial illustrated how to use WebSphere Studio Application Developer, Integrated Edition, Version 5, to create a basic EJB application that uses Extended Messaging. The information presented here can also be used as a building block for experimenting with more advanced EMS functions, which will be explored further in an upcoming article.

Back to top

Download

Name	Size	Download method
emsSample.ear	0.1 MB	FTP|HTTP

Information about download methods

Resources

• "Using Extended Messaging in Applications" in the WebSphere Application Server information center
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Extended Messaging Service overview
• Sample application
• Building the EMS application
• Configuring, running and testing an EMS application
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers