Introduction to the JMS API Programming Model
- Administered Ojbects
- Connections
- Sessions
- Message Producers
- Message Consumers
- Messages
- Exception Handling
This chapter is from the book
This chapter is from the book
This chapter is from the book
The basic building blocks of a JMS application consist of
- Administered objects: connection factories and destinations
- Connections
- Sessions
- Message producers
- Message consumers
- Messages
Figure 3.1 shows how all these objects fit together in a JMS client application.
)
Figure 3.1 The JMS API Programming Model
This chapter describes all these objects briefly and provides sample commands and code snippets that show how to create and use the objects. The last section briefly describes JMS API exception handling.
Examples that show how to combine all these objects in applications appear in later chapters. For more details, see the JMS API documentation, which you can download from the JMS Web site, http://java.sun.com/products/jms/.
3.1 Administered Objects
Two parts of a JMS application—destinations and connection factories—are best maintained administratively rather than programmatically. The technology underlying these objects is likely to be very different from one implementation of the JMS API to another. Therefore, the management of these objects belongs with other administrative tasks that vary from provider to provider.
JMS clients access these objects through interfaces that are portable, so a client application can run with little or no change on more than one implementation of the JMS API. Ordinarily, an administrator configures administered objects in a Java Naming and Directory Interface (JNDI) API namespace, and JMS clients then look them up, using the JNDI API. J2EE applications always use the JNDI API.
With the J2EE Software Development Kit (SDK) version 1.3, you use a tool called j2eeadmin to perform administrative tasks. For help on the tool, type j2eeadmin with no arguments.
3.1.1 Connection Factories
A connection factory is the object a client uses to create a connection with a provider. A connection factory encapsulates a set of connection configuration parameters that has been defined by an administrator. A pair of connection factories come preconfigured with the J2EE SDK and are accessible as soon as you start the service. Each connection factory is an instance of either the QueueConnectionFactory or the TopicConnectionFactory interface.
With the J2EE SDK, for example, you can use the default connection factory objects, named QueueConnectionFactory and TopicConnectionFactory, to create connections. You can also create new connection factories by using the following commands:
j2eeadmin -addJmsFactory jndi_name queue
j2eeadmin -addJmsFactory jndi_name topicAt the beginning of a JMS client program, you usually perform a JNDI API lookup of the connection factory. For example, the following code fragment obtains an InitialContext object and uses it to look up the QueueConnectionFactory and the TopicConnectionFactory by name:
Context ctx = new InitialContext(); QueueConnectionFactory queueConnectionFactory = (QueueConnectionFactory) ctx.lookup("QueueConnectionFactory"); TopicConnectionFactory topicConnectionFactory = (TopicConnectionFactory) ctx.lookup("TopicConnectionFactory");Calling the InitialContext method with no parameters results in a search of the current classpath for a vendor-specific file named jndi.properties. This file indicates which JNDI API implementation to use and which namespace to use.
3.1.2 Destinations
A destination is the object a client uses to specify the target of messages it produces and the source of messages it consumes. In the PTP messaging domain, destinations are called queues, and you use the following J2EE SDK command to create them:
j2eeadmin -addJmsDestination queue_name queueIn the pub/sub messaging domain, destinations are called topics, and you use the following J2EE SDK command to create them:
j2eeadmin -addJmsDestination topic_name topicA JMS application may use multiple queues and/or topics.
In addition to looking up a connection factory, you usually look up a destination. For example, the following line of code performs a JNDI API lookup of the previously created topic MyTopic and assigns it to a Topic object:
Topic myTopic = (Topic) ctx.lookup("MyTopic");The following line of code looks up a queue named MyQueue and assigns it to a Queue object:
Queue myQueue = (Queue) ctx.lookup("MyQueue");