1. Using Oracle Messaging Cloud Service
  2. Accessing Oracle Messaging Cloud Service Using Java Library
  3. Using Extensions to the JMS API

Using Extensions to the JMS API

The Oracle Messaging Cloud Service Java library extends the Java Message Service (JMS) 1.1 interface.

Topics:

Safe Durable Subscriptions

The Oracle Messaging Cloud Service Java library provides a method to obtain a consumer on a durable subscription safely in the sense that the creation of the consumer will not create a subscription that does not already exist and will not destroy an existing subscription.

In JMS 1.1, a durable subscription is not directly represented as a Java object. What is represented is a consumer on a durable subscription. Such consumers are called durable subscribers, and are created by invoking one of the two createDurableSubscriber() methods on a JMS Session.

An invocation of a createDurableSubscriber() method is always passed a Topic object (representing the topic on which to create a durable subscriber) and a name, which is the name of the subscription. The Session object on which the method is invoked must have been created from a Connection object that had a client ID set on it prior to the session's creation. One of the createDurableSubscriber() methods also takes a selector that will define a subset of messages that will be delivered to the durable subscriber.

A durable subscription is uniquely identified by its associated client ID and subscription name. The topic subscribed to and the selector, if any, are properties of the durable subscription.

The first unsafe aspect of the JMS methods is that creating a durable subscription with a given client ID and subscription name will create a durable subscription corresponding to the client ID and subscription if one does not exist when the method is called. If a client means to access an existing durable subscription, but gets the wrong client ID or subscription name (for example, due to a typographical error in code or data), it will simply create and begin to access a new durable subscription. Meanwhile, the durable subscription it means to access may be holding messages that the client will miss.

The second unsafe aspect of the JMS methods is their behavior when a durable subscriber is created on an existing durable subscription, but the topic or selector specified is different from that of the existing durable subscription. In this case, the JMS 1.1 standard specifies that the existing durable subscription be deleted, discarding all messages it is holding, and a new durable subscription be created on the new topic or with the new selector, or both. This may cause messages to be lost if a mistake in code or data causes a client to change the topic or selector of an existing durable subscription inadvertently.

The Oracle Messaging Cloud Service extension of the JMS Session interface is oracle.cloud.messaging.client.OracleCloudSession has two additional createDurableSubscriber() methods that are not part of the JMS 1.1 interface. Each method takes a subscription name, but no Topic object or selector. The methods return a consumer on an existing durable subscription with the client ID from the Connection object and the subscription name supplied to the invocation. If no durable subscription with the specified client ID and subscription name exists, the method will throw an exception.

Strong Typing for JMS

The Oracle Messaging Cloud Service Java library adds several classes that can make code more strongly typed and self-documenting, which can improve code quality.

The use of the Java library classes, and the methods that take them as parameters, is optional, except in the case of a method for safe durable subscriptions, which uses the LocalMode class.

The strong typing additions fall into two categories: Java enumeration classes and wrapper classes.

Enumerations

In several methods in the JMS 1.1 API, parameters that indicate one of a small number of alternatives are represented by Java boolean or short values. In the Oracle Messaging Cloud Service Java library, these parameters can be represented by Java enumeration types.

The enumeration classes are:

  • AcknowledgementMode: Represents whether the acknowledgement mode of a session is auto-acknowledge, client-acknowledge, or duplicates-ok, and replaces the use of codes of type short.

  • DeliveryMode: Represents whether a message is persistent or non-persistent, and replaces the use of codes of type short.

  • LocalMode: Represents whether a consumer on a topic will receive messages sent through the connection that the consumer uses, and replaces the use of boolean.

  • TransactionMode: Represents whether a session is transacted or not, and replaces the use of boolean.

Wrapper Classes

In several methods in the JMS 1.1 API, parameters with specific meanings and limitations on their values are represented by Java types or classes such as int, long, or String.

In the Oracle Messaging Cloud Service Java library, these parameters can be represented by classes that "wrap" the Java types and classes used in JMS 1.1. These "wrapper" classes enforce some of the restrictions on the wrapped values that are required by JMS 1.1, and generally improve the typing discipline of JMS. With the wrapper classes, you can supply null to the send() methods that take those classes and have the default used. Also, when using the send() methods that take the wrapper classes as parameters, you can supply null for a parameter and the producer-specified default will be used.

The wrapper classes are:

  • TimeToLive: Represents the time-to-live of a message, and replaces the use of long. Use of this type ensures that inappropriate or disallowed values, such as values less than or equal to 0, cannot be passed. It also allows clients to specify the maximum time-to-live allowed by Oracle Messaging Cloud Service without having to know what that maximum is.

  • Selector: Represents a selector for a consumer, durable subscription, or message push listener, and replaces the use of String. Currently, this class is a simple wrapper for a String. In future versions, the wrapper may incorporate syntax checking of the String and support programmatic mechanisms for constructing a selector that is guaranteed to be well-formed.

  • Priority: Represents the priority of a message, and replaces the use of int. Use of this type ensures that only int values that correspond to a JMS 1.1 priority value can be passed. Oracle Messaging Cloud Service does not currently support priorities other than the default (4), so supplying priority values other than the default will be ignored. Priorities may be supported in a future release.

Connection Timeout

The Oracle Messaging Cloud Service Java library provides methods for controlling a Connection's timeout.

The Oracle Messaging Cloud Service extension of the JMS Connection interface is oracle.cloud.messaging.client.OracleCloudConnection. Some implementations of this interface support setting a timeout on the Connection. If a client fails or loses network connectivity to the messaging service, after the timeout has passed, the service will release resources reserved for the client. In particular, if a Connection is created with a client ID set on it, and the client fails or loses network connectivity to the messaging service, that client ID will continue to be reserved (and cannot be set on another connection) until the timeout has passed. As long as the client is running and has connectivity to the service, the timeout should not expire. The timeout is measured in seconds, must be positive, is initialized to 300 (5 minutes), and can be set to a maximum of 900 (15 minutes).

Refer to the following methods for controlling a connection's timeout in the Java library:

Obtaining Service Version

The Oracle Messaging Cloud Service Java library provides the getServerVersion() method of the OracleCloudConnection class to obtain the version of the Oracle Messaging Cloud Service being run by the server to which the client is connected.

Refer to the following for details:

Obtaining Messaging Context ID

The Oracle Messaging Cloud Service Java library provides the getMessagingContextId() method of the OracleCloudConnection class to obtain the messaging context ID for a given Connection.

Refer to the following for details: