ConnectionFactory Creation API

This topic provides information about the ConnectionFactory object.

In the Oracle Messaging Cloud Service Java library, a JMS ConnectionFactory object is obtained from a MessagingService object by invoking the getConnectionFactory() method on the MessagingService object. The object returned has class oracle.cloud.messaging.client.OracleCloudConnectionFactory, which is the Oracle Messaging Cloud Service extension of ConnectionFactory. Note that this is different from the suggested method of obtaining ConnectionFactory objects from an instance of the Java Naming and Directory Interface (JNDI) as specified in the JMS 1.1 standard. Oracle Messaging Cloud Service does not currently support JNDI access to ConnectionFactory objects.

The MessagingService class also has methods getQueueConnectionFactory() and getTopicConnectionFactory(). These methods are provided purely for backward compatibility with JMS 1.0, in which separate connection factory classes are implemented for queues and topics. The separate connection factory methods should not be used unless it is necessary to use Oracle Messaging Cloud Service with legacy JMS 1.0 code that requires the use of QueueConnectionFactory or TopicConnectionFactory objects.

The Java library includes methods to create ConnectionFactory, QueueConnectionFactory, and TopicConnectionFactory objects that set a fixed client ID on the Connection, QueueConnection, or TopicConnection objects that they create. If such a ConnectionFactory object is created, any Connection it creates must be closed before the ConnectionFactory can be used to create another Connection, since there can only be one Connection with a given client ID.

Note:

Connection objects that you create via the Java library should be closed if you are not going to use them further. This is because Connection objects consume computing and network resources on both the client and the server side, and failing to close them wastes these resources.

References to Connection objects that have not been closed should not just be discarded, with the Connection being taken care of by garbage collection. If resources held by Connections are allowed to be released by garbage collection then there may be a substantial delay between when a Connection reference is discarded and when garbage collection occurs. This causes server and network resources to be wasted.

ConnectionFactory Control of Thread Pools

An API has been added to OracleCloudConnectionFactory to control the client-side use of thread pools. Some implementations of this interface support setting a thread pool (an instance of java.util.concurrent.Executor) for the ConnectionFactory. This thread pool is used to obtain threads to execute concurrent operations like processing asynchronously received Message objects via a MessageListener.

By default, the thread pool is of the sort returned by java.util.concurrent.Executors.newCachedThreadPool(). This is a pool that is initially empty, creates new threads as needed, and re-uses previously started threads in the pool. When a thread is returned to the pool, it remains available for re-use for 60 seconds, after which it is terminated. The threads managed by the default thread pool are all daemon threads.

Connections that are created while a ConnectionFactory is using a given thread pool will continue to use threads from that thread pool for concurrent operations. For example, if a ConnectionFactory is created, and is used to create five Connections, and the ConnectionFactory's thread pool is then set to a different thread pool, future Connections will use the new thread pool, but the first five Connections will use the default thread pool.

Oracle Cloud Messaging Service implementations of JMS that support setting thread pools will interact with those thread pools solely via the java.util.concurrent.Executor interface. They will not shut down or otherwise manage such thread pools. If a client sets the thread pool of a ConnectionFactory, it must do any configuration, startup, shutdown, or other management itself. When a thread pool is used to execute a concurrent operation, if the attempt to start that operation in a thread throws an exception (for example, because the thread has a maximum pool size, and that size has been reached), it will cause a JMSException to be thrown by the JMS operation that attempted to start the concurrent operation (for example, setMessageListener() on a MessageConsumer). Implementations of this interface that support setting thread pools and are serializable will re-initialize the thread pool to the default thread pool when de-serialized.