Overview

GigaSpaces offers a virtual JMS implementation, built on top of the core JavaSpaces layer. The JMS implementation is basically a client-side view of specific objects in a space. This associative approach is a key factor in enabling the virtualization of a queue or a topic. In general, a queue or a topic is mapped to a set of objects of a specific class name – the queue/topic name ordered at the time they were written.

Basic JMS Workflow

Applications using GigaSpaces as the JMS provider should use the following basic process:

1. Create a connection to the JMS client and obtain a Connection object. This step initiates a communications channel to the JMS client and approves it.
2. Obtain a Session object for this connection. A Session is a factory that creates message producer and consumer objects, all operating within the same thread. In other words, if a client wants one thread to produce messages and other threads to consume them, the client must use a separate Session for each producing thread.
3. Obtain a Queue or Topic object that parallels the particular message destination you desire.

   Remember that point-to-point messaging uses queues, while publish-and-subscribe messaging uses topics.

   The resulting message-producing application creates a message-producer object that corresponds to the session as well as to the particular queue or topic desired.

4. When the application is finished, it should:
   • Close any message producer or message consumer objects.
   • Close the session.
   • Close the connection.

Optional Workflow Steps

The following actions can be performed during the basic interaction process described above:

• To send messages to a queue, use a QueueSender object (see Point-to-Point Messaging).

• To publish messages to a topic, use a TopicPublisher object (see Publish and Subscribe Messaging).

• To create a Message object with the necessary payload, use the message producer to send or publish that message. The message-consuming application creates a message consumer object that parallels the session as well as the particular queue or topic from which it wishes to consume the messages.

• To receive messages from a queue, use a QueueReceiver (see Point-to-Point Messaging).

• To subscribe to messages on a particular topic, use a TopicSubscriber (see Publish and Subscribe Messaging).

• To start delivery of incoming messages, call start() on the Connection object.

• To wait for messages to arrive synchronously, call receive() on the message consumer.

• To wait for messages to arrive asynchronously, define a MessageListener object. The onMessage() method should be invoked when a message is received.

Section Contents

• About JMS Messages — Messages types, headers, and properties; creating a message.
• Closing Down JMS — Closing message consumer objects, open sessions, and the JMS connection.
• GigaSpaces JMS Limitations — Known limitations of the GigaSpaces virtual JMS implementation.
• JMS Local Transactions — Starting, committing, rolling back; sending/consuming messages under local transaction; avoiding redelivery loops.
  • Avoiding Redelivery Loops in JMS Local Transactions — It is recommended not to use an application that rolls back the transaction when an error happens.
  • Committing Local Transaction in JMS — You commit a local transaction by calling the commit() method on the Session object.
  • Consuming JMS Messages Under Local Transaction — You can create a QueueReceiver or TopicSubscriber and call setMessageListener() to register a listener, or receive() to receive a message.
  • Rolling Back Local Transaction in JMS — You roll back a local transaction by calling the rollback() method on the Session object.
  • Sending JMS Messages Under Local Transaction — After started a local transaction, you can create a QueueSender or TopicPublisher and send() or publish() messages.
  • Starting Local Transaction in JMS — Create a transacted JMS session automatically starts a local transaction.
• JMS User Security — How to specify a username and password when creating the JMS connection.
• Message Selectors — Allowing the JMS provider, instead of each client, to select messages for deletion.
• Obtaining JMS Connection — How to obtain a connection, either by creating a connection factory or obtaining it with JNDI.
• Obtaining JMS Destination — Obtaining a destination from the session or using JNDI, and binding destination to the JNDI namespace.
  • Binding JMS Destination to JNDI Namespace — Two methods of binding non-persistent JMS destinations.
  • Obtaining JMS Destination from Session Object — The easiest way to obtain a JMS destination – from the Session object.
  • Obtaining JMS Destination Using JNDI — When a queue or topic exists and is stored in a JNDI namespace, the client can look it up by its JNDI name.
• Obtaining JMS Session — How to obtain a JMS session for transacted or non-transacted sessions, and for P2P queues or Pub/Sub topics.
  • Non-Transacted JMS Sessions — When isTransacted is set to false, the session is non-transacted and acknowledgeMode specifies how messages are acknowledged.
  • Transacted JMS Sessions — When isTransacted is set to true, the session is transacted and the argument acknowledgeMode is ignored.
• Point-to-Point Messaging — Creating a QueueSender, sending messages, creating a QueueReceiver, receiving messages (sync/async), browsing messages.
• Publish and Subscribe Messaging — Creating a TopicPublisher, publishing messages, creating a TopicSubscriber, receiving messages (sync/async), durable subs.
  • Creating TopicPublisher — A JMS client can publish messages to a topic with a TopicPublisher.
  • Creating TopicSubscriber — A JMS client subscribes to a topic with a TopicSubscriber.
  • JMS Durable Subscriptions — In a durable subscription, if the subscriber is not running messages that it would likely receive are stored by the JMS provider, and delivered when the subscriber is restarted.
  • Publishing Messages — After obtaining a TopicPublisher, you can publish messages using one of the publish() methods.
  • Receiving JMS Messages Asynchronously — Receiving a message asynchronously, by creating an object that implements MessageListener and registering it with the TopicSubscriber.
  • Receiving JMS Messages Synchronously — Receiving messages synchronously by calling one of the receive() methods on the TopicSubscriber.