JMS Overview 

Purpose

The JMS programming model describes how to use JMS from an application. To use the Java Message Service (JMS) in your application, you first have to obtain the initial JNDI context, then you look up a connection factory and a destination (topic or queue). You use the connection factory to create a connection and then the connection to create a session. Then you use the session to create a producer and/or a consumer to a previously looked up destination. The session is also used to create JMS messages, which can be sent to the destination using the producer and subsequently received by the consumer.

Process Flow

Step 1: Obtain the server’s initial JNDI context

Specify the connection and the security properties required to obtain the initial JNDI context:

java.util.Properties properties = new Properties(); // set the properties of the connection properties.put(    Context.INITIAL_CONTEXT_FACTORY,    "com.sap.engine.services.jndi.InitialContextFactoryImpl"); properties.put(Context.SECURITY_PRINCIPAL, "Administrator"); properties.put(Context SECURITY_CREDENTIALS, "admin_password"); // start initial context with the properties specified InitialContext context = new InitialContext(properties);

The properties that have to be set may differ depending on the client type. For example, internal clients of the server (in other words, deployed on it) do not need to specify any properties, while external (remote) clients have to specify additional properties.

Step 2: Look up a connection factory

The JMS Provider has predefined the following (default) connection factories:

●      TopicConnectionFactory– enables you to create a topic connection.

●      QueueConnectionFactory– enables you to create a queue connection.

●      XATopicConnectionFactory – enables you to create a transacted topic connection.

●      XAQueueConnectionFactory – enables you to create a transacted queue connection.

To perform a lookup operation, you also need a resource reference entry for the relevant administered object in the deployment descriptor of the component that looks up the object:

●      Declare a JMS connection factory in the <res-ref-name>element of the standard deployment descriptor for the relevant application component. The name that you specify in the <res-ref-name> tag is the name used for the lookup operation.

To register a connection factory, use the JMS Connector service.

●      Declare a JMS Destination resource in the <res-env-ref-name> element of the standard deployment descriptor of the application component. The name that you specify in the <res-env-ref-name> tag is the name used for the lookup operation.

To look up a queue connection factory, use the following code:

QueueConnectionFactory queueConnectionFactory = (QueueConnectionFactory) context.lookup("java:comp/env/<res-ref-name>");

Step 3: Create a connection

Using the connection factory object, create the connection object:

// create connection QueueConnection  queueConnection = connectionFactory.createQueueConnection(user, password);

or in case you want to provide a user name and password:

// create connection TopicConnection topicConnection = topicConnectionFactory.createTopicConnection();

Step 4: Start a session

Using the connection object, create the session object, providing the necessary session parameters:

// create session QueueSession queueSession = queueConnection.createQueueSession(false/true, Session.CLIENT_ACKNOWLEDGE/Session.DUPS_OK_ACKNOWLEDGE);

The first parameter shows if the session is transacted. The second parameter specifies the acknowledgement mode. For more information about the message acknowledgement types, see Message Acknowledgement.

The session cannot be accessed concurrently from different threads according to the JMS specification, so if you are coding a multithreaded application, you will have to create and use a separate session object for each thread.

Step 5: Create or look up a destination

Since destinations are administered objects, they must be created using an administrative tool. Note that the createQueue() and createTopic() methods of the session, despite their names, are not required by the specification to physically create a destination, they just fetch an already existing one. SAP’s JMS Provider implementation of these methods physically creates the destination, if it does not exist, but we strongly discourage you from relying on this functionality because it is completely vendor-specific and, therefore, not portable.

●      For example, to create a topic, use the following code:

// retrieve an existing destination of type topic Topic topic = session.createTopic("Example_topic_name");

●      To look up a destination, use the following code:

Queue queue= (Queue) context.lookup("java:comp/env/<res-env-ref-name>");

In some scenarios you can choose to create and use temporary destinations.

For more information, see: Destinations.

Step 6: Create a message producer or consumer

To create a message consumer on a queue, use the following code:

// create a queue receiver QueueReceiver queueReceiver = queueSession.createReciver(queue);

To create a message producer on a topic, use the following code, assuming that the topicSession is creating in steps analogous to the queue session:

// create a topic publisher TopicPublisher topicPublisher = topicSession.createPublisher(topic);

Consumers, producers and messages must not be accessed concurrently from different threads according to the JMS specification.

Step 7: Send or receive messages

Now you can use the message producers and/or consumer you have created in the previous step.

For more information, see: JMS Client Example.

Step 8: Close the connection

When you have finished using the JMS connection, close all producers, consumers, sessions and the connection itself. This will release the resources that have been allocated for these objects on the server. For more information, see Closing the JMS Connection.