• Home
• jakarta.jms
• jakarta.jms-api
• 2.0.2
• source code
• package.html

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

javax.jms.package.html Maven / Gradle / Ivy

The Java Message Service (JMS) API provides a common way for Java programs to create, send, receive and read an enterprise messaging system's messages. 

JMS Applications

A JMS application is composed of the following parts:


  
JMS provider - a messaging system that implements the JMS API
      in addition to the other administrative and control functionality required 
      of a full-featured messaging product
  
JMS clients - the Java language programs that send and receive 
      messages

  
Messages - objects that are used to communicate information between the 
      clients of an application
  
Administered objects - provider-specific objects that clients look up
      and use to interact portably with a JMS provider
  
Non-JMS clients - clients that use a message system's native 
      client API instead of the JMS API. If the application predated the 
      availability of the JMS API, it is likely that it will include both JMS 
      clients and non-JMS clients.


Administration

JMS providers differ significantly in their implementations of 
underlying messaging technology. There are also major 
differences in how a JMS provider's system is installed and administered.

For JMS clients to be portable, they must be isolated from these 
proprietary aspects of a provider. This is done by defining JMS administered
objects that are created and customised by a provider's administrator and 
later used by clients. The client uses them through JMS interfaces that are 
portable. The administrator creates them using provider-specific facilities.

There are two types of JMS administered objects:


  
{@code ConnectionFactory} - the object a client uses to create a 
      connection with a JMS provider
  
{@code Destination} - the object a client uses to specify the 
      destination of messages it is sending and the source of messages 
      it receives


Administered objects are placed by an administrator in a JNDI (Java Naming and Directory 
Interface) namespace.
A JMS client typically notes in its documentation the JMS administered objects 
it requires and how the JNDI names of these objects should be provided to it.

Two Messaging Styles

JMS supports two styles of messaging:

point-to-point (PTP) messaging using queues
publish-and-subscribe (pub/sub)messaging using topics

These two styles represent two of the dominant approaches to messaging currently in use.  

JMS APIs

For historical reasons JMS offers four alternative sets of interfaces for sending and receiving messages:

JMS 1.0 defined two domain-specific APIs, one for point-to-point messaging (queues) 
and one for pub/sub (topics). Although these remain part of JMS for reasons of backwards 
compatibility they should be considered to be completely superseded by the later APIs.
JMS 1.1 introduced a new unified API which offered a single set of interfaces that could 
be used for both point-to-point and pub/sub messaging. This is referred to here as the classic API.
JMS 2.0 introduces a simplified API which offers all the features of the classic API but 
which requires fewer interfaces and is simpler to use.



Each API offers a different set of interfaces for connecting to a JMS provider and for sending
and receiving messages. However they all share a common set of interfaces for representing 
messages and message destinations and to provide various utility features.

All interfaces are in the {@code javax.jms} package. 

Interfaces common to multiple APIs

The main interfaces common to multiple APIs are as follows:

{@code Message}, {@code BytesMessage}, {@code MapMessage}, {@code ObjectMessage}, {@code StreamMessage} and {@code TextMessage} - 
     a message sent to or received from a JMS provider.
{@code Queue} - an administered object that encapsulates the identity of a message destination for point-to-point messaging
{@code Topic} - an administered object that encapsulates the identity of a message destination for pub/sub messaging.
{@code Destination} - the common supertype of {@code Queue} and {@code Topic}


Classic API interfaces

The main interfaces provided by the classic API are as follows:

{@code ConnectionFactory} - an administered object used by a client to create a {@code Connection}. This interface is also used by the simplified API.
{@code Connection} - an active connection to a JMS provider
{@code Session} - a single-threaded context for sending and receiving messages
{@code MessageProducer} - an object created by a Session that is used for sending messages to a queue or topic
{@code MessageConsumer} - an object created by a Session that is used for receiving messages sent to a queue or topic


Simplified API interfaces

The simplified API provides the same messaging functionality as the classic API but requires fewer interfaces and is simpler to use.
The main interfaces provided by the simplified API are as follows:

{@code ConnectionFactory} - an administered object used by a client to create a {@code JMSContext}. This interface is also used by the classic API.
{@code JMSContext} - an active connection to a JMS provider and a single-threaded context for sending and receiving messages
{@code JMSProducer} - an object created by a {@code JMSContext} that is used for sending messages to a queue or topic
{@code JMSConsumer} - an object created by a {@code JMSContext} that is used for receiving messages sent to a queue or topic


Legacy domain-specific API interfaces


Although the domain-specific API remains part of JMS for reasons of backwards compatibility it should be considered 
to be completely superseded by the classic and simplified APIs.

The main interfaces provided by the domain-specific API for point-to-point messaging are as follows:


{@code QueueConnectionFactory} - an administered object used by a client to create a {@code QueueConnection}.
{@code QueueConnection} - an active connection to a JMS provider
{@code QueueSession} - a single-threaded context for sending and receiving messages
{@code QueueSender} - an object created by a {@code QueueSession} that is used for sending messages to a queue
{@code QueueReceiver} - an object created by a {@code QueueSession} that is used for receiving messages sent to a queue


The main interfaces provided by the domain-specific API for pub/sub messaging are as follows:

{@code TopicConnectionFactory} - an administered object used by a client to create a {@code TopicConnection}.
{@code TopicConnection} - an active connection to a JMS provider
{@code TopicSession} - a single-threaded context for sending and receiving messages
{@code TopicPublisher} - an object created by a {@code TopicSession} that is used for sending messages to a topic
{@code TopicSubscriber} - an object created by a {@code TopicSession} that is used for receiving messages sent to a topic


Terminology for sending and receiving messages

The term consume is used in this document to mean the receipt of a message by a JMS client; that is, 
a JMS provider has received a message and has given it to its client. 
Since JMS supports both synchronous and asynchronous receipt of messages, 
the term consume is used when there is no need to make a distinction between them.

The term produce is used as the most general term for sending a message. 
It means giving a message to a JMS provider for delivery to a destination.

Developing a JMS Application

Broadly speaking, a JMS application is one or more JMS clients that exchange 
messages. The application may also involve non-JMS clients; however, these 
clients use the JMS provider's native API in place of the JMS API.

A JMS application can be architected and deployed as a unit. In many cases, 
JMS clients are added incrementally to an existing application.

The message definitions used by an application may originate with JMS, or they 
may have been defined by the non-JMS part of the application.

Developing a JMS Client

A typical JMS client using the classic API executes the following JMS setup procedure:

Use JNDI to find a {@code ConnectionFactory} object
Use JNDI to find one or more {@code Destination} objects
Use the ConnectionFactory to create a JMS {@code Connection} object with message delivery inhibited
Use the Connection to create one or more JMS {@code Session} objects
Use a Session and the Destinations to create the {@code MessageProducer} and {@code MessageConsumer} objects needed
Tell the {@code Connection} to start delivery of messages


In contrast, a typical JMS client using the simplified API does the following:

Use JNDI to find a {@code ConnectionFactory} object
Use JNDI to find one or more {@code Destination} objects
Use the {@code ConnectionFactory} to create a {@code JMSContext} object
Use the {@code JMSContext} to create the {@code JMSProducer} and {@code JMSConsumer} objects needed.
Delivery of message is started automatically



At this point a client has the basic JMS setup needed to produce and consume messages. 

Package Specification


  Java Message Service 2.0 specification


Related Documentation


  Java Platform, Enterprise Edition (Java EE) Technical Documentation