Accessing Oracle Messaging Cloud Service Using Java Library

Client-Side Logging

Certain events are logged by the Java library on the Java platform that runs the client software.

Event logging is done via the java.util.logging framework, using the logging levels of java.util.logging.Level. Events may be useful in diagnosing the cause of problems, or may be useful input to Support.

Events are logged at the WARNING and SEVERE levels in two packages: oracle.cloud.messaging.client and oracle.cloud.messaging.util.

Package	Log Level	Log Message	Description
`oracle.cloud.messaging.client`	SEVERE	Exception shutting down thread pool	An exception was thrown when a Connection was being closed. This occurred when an attempt was made to shut down a thread pool used for background operations like executing `MessageListeners`. The exception thrown is logged.
		Exception stopping REST client	An exception was thrown when a Connection was being closed. This occurred when an attempt was made to stop the HTTP client by which the Java library communicates with the REST API. The exception thrown is logged.
		Exception deleting connection	An exception was thrown when attempting to close and delete the server-side Connection associated with a client-side Connection. The exception thrown is logged.
		Exception shutting down messaging context	An exception was thrown when attempting to shut down the server-side messaging context associated with a client-side Connection. The exception thrown is logged.
		Exception disconnecting HTTP connection	An exception was thrown when attempting to disconnect a network connection from the client to the server. The exception thrown is logged.
		Exception on client-side session close	An exception was thrown when a Connection was being closed. This occurred when an attempt was made to shut down a Session created from the Connection. The exception thrown is logged.
	WARNING	Closing unclosed Connection in finalizer	A Connection was closed when the Connection object was garbage-collected; this indicates that a reference to a Connection was discarded without calling `close()` on the Connection.
`oracle.cloud.messaging.util`	WARNING	Runtime exception thrown from exception listener	The HTTP client encountered an exception attempting to reach the server, and the listener that handles such exceptions threw a RuntimeException. The exception thrown is logged.

Automatic Closing of Connections

This section provides information about situations in which Connections close automatically.

Connections Close if Server is Unreachable for a Sufficiently Long Period of Time

If a Java library client cannot reach the Oracle Messaging Cloud Service server for a sufficiently long period of time, Connections for that client will be closed. The amount of time before a Connection is closed is given by the Connection’s timeout, plus an additional margin for error to allow for clock skew between the client and server.

During the period in which the client is unable to reach the server, client operations will throw exceptions, but a Connection will not be closed until the server has been unreachable for longer than the Connection’s timeout. When a Connection is closed for this reason, if the Connection has an ExceptionListener set on it, a JMSException will be dispatched to the Connection's ExceptionListener.

Connections Close if Server-Side State is Lost

Connections may detect that their server-side state has expired or been lost. This may be because the client was unable to reach the server for a certain period, or because the server failed due to other reasons. When the Java library detects that it has lost the server-side state for a Connection, the Connection will be closed. When a Connection is closed for this reason, if the Connection has an ExceptionListener set on it, a JMSException will be dispatched to the Connection's ExceptionListener.

Diagnosing Errors from the Java Library

The Java library offers additional features for diagnosing exceptions beyond what is available from JMS.

When a JMSException (or one of its subclasses) is thrown by a method, or dispatched to an ExceptionListener, the exception may have a cause, which can be obtained by invoking getCause() on the exception object. If the cause is not null, and has class HttpResponseException, the cause will contain Messaging-Service-specific information about the error that caused the exception. In particular, it may contain an error key and an error message with further information.

For more information on HttpResponseException, see HttpResponseException in Java API Reference for Oracle Messaging Cloud Service. For details on the meaning of error information obtainable from HttpResponseException, see Error Keys, Status Codes and Error Messages.

Using the Re-try Function

When a request from the Java client library to Oracle Messaging Cloud Service receives a response that indicates that it is attempting to access a messaging context that has expired, it re-tries the request, with pauses, before throwing a JMSException.

By default, the library re-tries the request four times, pausing for one second before the first re-try, then two seconds between the first re-try and the second, then four seconds, then eight seconds. At any point, if the response to the re-try indicates that the messaging context has been found again, no further re-tries is made.

The number of re-tries, and pauses between them, can be changed by setting the oracle.cloud.messaging.client.retryWait property using the OracleCloudConnectionFactory.setProperty() method. The value set for this property must be a comma-separated list of long integers. The number of integers is the number of re-tries; each integer is the number of milliseconds to pause before the corresponding re-try.

For example, invoking setProperty("oracle.cloud.messaging.client.retryWait","1000,10000") on an OracleCloudConnectionFactory object will change the re-try behavior to re-trying twice, waiting one second before the first re-try and ten seconds between the first and second re-tries.

Setting the oracle.cloud.messaging.client.retryWait property to null disables re-tries.