Azure Service Bus JMS 2.0 developer guide
This guide contains detailed information to help you succeed in communicating with Azure Service Bus using the Java Message Service (JMS) 2.0 API.
As a Java developer, if you are new to Azure Service Bus, please consider reading the below articles.
Java Message Service (JMS) Programming model
The Java Message Service API programming model is as shown below -
Azure Service Bus Premium tier supports JMS 1.1 and JMS 2.0.
Azure Service Bus - Standard tier supports limited JMS 1.1 functionality. For more details, please refer to this documentation.
JMS - Building blocks
The below building blocks are available to communicate with the JMS application.
The below guide has been adapted from the Oracle Java EE 6 Tutorial for Java Message Service (JMS)
Referring to this tutorial is recommended for better understanding of the Java Message Service (JMS).
The connection factory object is used by the client to connect with the JMS provider. The connection factory encapsulates a set of connection configuration parameters that are defined by the administrator.
Each connection factory is an instance of
To simplify connecting with Azure Service Bus, these interfaces are implemented through
ServiceBusJmsTopicConnectionFactory respectively. The Connection factory can be instantiated with the below parameters -
- Connection string - the connection string for the Azure Service Bus Premium tier namespace.
- ServiceBusJmsConnectionFactorySettings property bag which contains
- connectionIdleTimeoutMS - idle connection timeout in milliseconds.
- traceFrames - boolean flag to collect AMQP trace frames for debugging.
- other configuration parameters
The factory can be created as below. The connection string is a required parameter, but the additional properties are optional.
ConnectionFactory factory = new ServiceBusJmsConnectionFactory(SERVICE_BUS_CONNECTION_STRING, null);
Java applications leveraging JMS 2.0 API must connect to Azure Service Bus using the connection string only. Currently, authentication for JMS clients is only supported using the Connection string.
Azure active directory (AAD) backed authentication is not currently supported.
A destination is the object a client uses to specify the target of the messages it produces and the source of the messages it consumes.
Destinations map to entities in Azure Service Bus - queues (in point to point scenarios) and topics (in pub-sub scenarios).
A connection encapsulates a virtual connection with a JMS provider. With Azure Service Bus,this represents a stateful connection between the application and Azure Service Bus over AMQP.
A connection is created from the connection factory as shown below.
Connection connection = factory.createConnection();
A session is a single-threaded context for producing and consuming messages. It can be utilized to create messages, message producers and consumers, but it also provides a transactional context to allow grouping of sends and receives into an atomic unit of work.
A session can be created from the connection object as shown below.
Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);
A session can be created with any of the below modes.
|Session.AUTO_ACKNOWLEDGE||The session automatically acknowledges a client's receipt of a message either when the session has successfully returned from a call to receive or when the message listener the session has called to process the message successfully returns.|
|Session.CLIENT_ACKNOWLEDGE||The client acknowledges a consumed message by calling the message's acknowledge method.|
|Session.DUPS_OK_ACKNOWLEDGE||This acknowledgment mode instructs the session to lazily acknowledge the delivery of messages.|
|Session.SESSION_TRANSACTED||This value may be passed as the argument to the method createSession(int sessionMode) on the Connection object to specify that the session should use a local transaction.|
When the session mode is not specified, the Session.AUTO_ACKNOWLEDGE is picked by default.
JMSContext is defined as part of the JMS 2.0 specification.
JMSContext combines the functionality provided by the connection and session object. It can be created from the connection factory object.
JMSContext context = connectionFactory.createContext();
Just like the Session object, the JMSContext can be created with the same acknowledge modes as mentioned in Session modes.
JMSContext context = connectionFactory.createContext(JMSContext.AUTO_ACKNOWLEDGE);
When the mode is not specified, the JMSContext.AUTO_ACKNOWLEDGE is picked by default.
JMS message producers
A message producer is an object that is created using a JMSContext or a Session and used for sending messages to a destination.
It can be created either as a stand alone object as below -
JMSProducer producer = context.createProducer();
or created at runtime when a message is needed to be sent.
JMS message consumers
A message consumer is an object that is created by a JMSContext or a Session and used for receiving messages sent to a destination. It can be created as shown below -
JMSConsumer consumer = context.createConsumer(dest);
Synchronous receives via receive() method
The message consumer provides a synchronous way to receive messages from the destination through the
If no arguments/timeout is specified or a timeout of '0' is specified, then the consumer blocks indefinitely unless the message arrives, or the connection is broken (whichever is earlier).
Message m = consumer.receive(); Message m = consumer.receive(0);
When a non-zero positive argument is provided, the consumer blocks until that timer expires.
Message m = consumer.receive(1000); // time out after one second.
Asynchronous receives with JMS message listeners
A message listener is an object that is used for asynchronous handling of messages on a destination. It implements the
MessageListener interface which contains the
onMessage method where the specific business logic must live.
A message listener object must be instantiated and registered against a specific message consumer using the
Listener myListener = new Listener(); consumer.setMessageListener(myListener);
Consuming from topics
Consumers on queues are simply client side objects that live in the context of the Session (and Connection) between the client application and Azure Service Bus.
Consumers on topics, however, have 2 parts -
- A client side object that lives in the context of the Session(or JMSContext), and,
- A subscription that is an entity on Azure Service Bus.
The subscriptions are documented here and can be one of the below -
- Shared durable subscriptions
- Shared non-durable subscriptions
- Unshared durable subscriptions
- Unshared non-durable subscriptions
JMS Queue Browsers
The JMS API provides a
QueueBrowser object that allows the application to browse the messages in the queue and display the header values for each message.
A Queue Browser can be created using the JMSContext as below.
QueueBrowser browser = context.createBrowser(queue);
JMS API doesn't provide an API to browse a topic.
This is because the topic itself doesn't store the messages. As soon as the message is sent to the topic, it is forwarded to the appropriate subscriptions.
JMS Message selectors
Message selectors can be used by receiving applications to filter the messages that are received. With message selectors, the receiving application offloads the work of filtering messages to the JMS provider (in this case, Azure Service Bus) instead of taking that responsibility itself.
Selectors can be utilized when creating any of the below consumers -
- Shared durable subscription
- Unshared durable subscription
- Shared non-durable subscription
- Unshared non-durable subscription
- Queue browser
AMQP disposition and Service Bus operation mapping
Here's how an AMQP disposition translates to a Service Bus operation:
ACCEPTED = 1; -> Complete() REJECTED = 2; -> DeadLetter() RELEASED = 3; (just unlock the message in service bus, will then get redelivered) MODIFIED_FAILED = 4; -> Abandon() which increases delivery count MODIFIED_FAILED_UNDELIVERABLE = 5; -> Defer()
This developer guide showcased how Java client applications using Java Message Service (JMS) can connect with Azure Service Bus.
For more information on Azure Service Bus and details about Java Message Service (JMS) entities, check out the links below -
- Service Bus - Queues, Topics, and Subscriptions
- Service Bus - Java Message Service entities
- AMQP 1.0 support in Azure Service Bus
- Service Bus AMQP 1.0 Developer's Guide
- Get started with Service Bus queues
- Java Message Service API(external Oracle doc)
- Learn how to migrate from ActiveMQ to Service Bus