An Advisory Message Listener object is used to listen for advisory messages. Applications wishing to listen for advisory messages should register their listeners on the JMS connection object.
FioranoMQ provides advisory messages to inform its client applications about situations that may affect them. The advisory messages provide errors and informational messages.
Advisory Messages
Below are some of the advisory messages supported by FioranoMQ:
- CONNECTION_STATE_CHANGED Event: Indicates a change in the state of Connection object.
- CSP_STATE_CHANGED: Indicates that forwarding of messages stored in persistent storage on the client side is starting or has been completed.
- CSP_ERROR_MESSAGE: Indicates that an error has occurred while forwarding the stored messages.
- CLIENT_APP_ERROR_MESSAGE: Indicates that an unhandled exception has been detected by FioranoMQ's RTL.
CONNECTION_STATE_CHANGED Event
This event is raised when the state of the connection object is changed. Below are the possible states of a connection object:
- FMQConnectionState.CONNECTION_ACTIVE: This state indicates that the connection is alive and available.
- FMQConnectionState.CONNECTION_STARTED: This state indicates that the connections are active and ready to deliver messages to the callback listeners. ACTIVE and STARTED are the same with the only difference reflected in consuming messages. For example, connection start() is invoked for consuming the messages and thus a different state is introduced.
- FMQConnectionState.CONNECTION_REVALIDATING: This state indicates that the connection is down, but indicates that the fmq client library is attempting to reconnect to the server.
- FMQConnectionState.CONNECTION_DISCONNECTED: This state indicates that the connection is down and the fmq client library has failed to reconnect to the server in the pre-specified attempts.
- FMQConnectionState.CONNECTION_CLOSED: This state indicates that the connection is in a closed state.
CONNECTION_STATE_CHANGED Event is raised for a durable connection. For a non- durable failed connection, the fmq client library throws a JMSException in the APIs (requiring a call to the Server).
Client applications listening for advisory messages can handle this event as per their application programming. One of the possible methods of handling such a situation is to log this event.
Below is the sample code that prints the connection state on the console:
Step 1: When an advisory message is received it checks whether the event is a Connection state change event. Type cast the message into the required FMQConnectionState object on verification.
Step 2: Using the above FMQConnectionState object, the current state of the connection object is printed. Possible values that maybe returned are:
Step 3: Prints whether the connection is active. This API compares getState () with FMQConnectionState.CONNECTION_ACTIVE or FMQConnectionState.CONNECTION_STARTED.
Step 4: Prints whether the connection has been disconnected. This API compares getState () with FMQConnectionState.CONNECTION_DISCONNECTED.
Step 5: Prints whether the connection attempts to reconnect to the server. This API compares getState () with FMQConnection-State.CONNECTION_REVALIDATING.
Step 6: Prints the URL to which the client is connected. If the client is not connected to a server 'null' is printed.
Step 7: Prints the list of backup URLs used in revalidation of the connection.
This message indicates a change in the state of the persistent store at the client end.
CSP_STATE_Changed is raised in the situations listed below:
- When the FioranoMQ client library has started transferring messages stored in the persistent store at the client side.
- When the FioranoMQ client library has transferred all the messages stored in the persistent store at the client end.
CSP_STATE_CHANGED is raised only for a durable connection. For non-durable connections, messages are not stored in the store at the client side.
Client applications listening for advisory messages can handle this event as per their application programming. One possible way of handling this situation is to log this event. is a sample of the code that prints the CSP_STATE_CHANGED on the console:
Step 1: When an advisory message is received, the code checks whether it is a CSP_STATE_CHANGED message. ype casts the message into the required CSP_STATE_CHANGED object on verification.
Step 2: Prints whether the fmq client library has started transferring the stored messages. If messages are currently being transferred, this API returns true. If messages are not being transferred it returns false.
Step 3: Prints whether the fmq client library has transferred all the locally stored messages. It returns true if the transfer is complete and false if the transfer is not complete.
CSP_ERROR_MESSAGE
This message indicates that an unexpected error occurred while forwarding the messages stored in the persistent store at the client end. Client applications log the error message so that the application administrators can investigate the cause of the error.
Below is a sample of the code that prints the CSP_ERROR_MESSAGE on the console.
Step 1: When an advisory message is received, the code checks whether it is a CSP_ERROR_MESSAGE or not. Type casts the message into the required CSP_ERROR_MESSAGE object on verification.
Step 2: Prints the exception stack on the console.
Step 3: Gets the message for csp corruption
This message indicates that an unhandled exception has been detected by FioranoMQ's RTL. An exception is thrown in the onMessage() method (a method in MessageListener of the MessageConsumer) of the user's code if the code has not been handled properly. This is actually a programming error in the client application. If such an uncaught exception inside the onMessage() method of the client application's MessageListener code occurs, it raises an advisory message Client_App_Error_Message. A MessageListener can be registered with a MessageConsumer for the purpose of receiving messages asynchronously.
The earlier versions of FioranoMQ's RTL handled this situation differently. When an exception inside the onMessage() method of the client code occured, the connection's ExceptionListener was notified through the invocation of its onException() method.
The sample code,below, demonstrates the registrationi of an advisory message listener:
Step 1: Create a .jms connection.
Step 2: Create an advisory message listener.
Step 3: Set the advisory message listener on the connection object.
For more details on Advisory Message APIs, please refer to the javadocs of the fiorano.jms.runtime package.