com.lightstreamer.jms_extender.hooks

Class JmsExtenderHook

java.lang.Object

com.lightstreamer.jms_extender.hooks.JmsExtenderHook

public abstract class JmsExtenderHook
extends java.lang.Object

Abstract class that defines a JMS Extender hook. By extending this class it is possible to receive notification for a number of operations requested by the users, including:

• connection openings,
• session openings,
• consumers and producers creation,
• durable subscriptions creation
• dedicated broker connection requests.

Constructor Summary

Constructors

Constructor and Description
JmsExtenderHook()

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	getDedicatedBrokerConnectionName(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String clientId) Dedicated JMS broker connection name mangling or decoration function.
java.lang.String	getDurableSubscriptionName(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String clientId, java.lang.String sessionGuid, java.lang.String subscriptionName, java.lang.String topicName) Durable subscription name mangling or decoration function.
void	init(java.io.File configDir) Hook initialization.
void	onConnectionClose(java.lang.String connectionId) User connection close notification.
boolean	onConnectionRequest(java.lang.String connectionId, java.lang.String user, java.lang.String password, java.util.Map clientContext, java.lang.String clientPrincipal) User connection and authentication request.
boolean	onDedicatedBrokerConnectionRequest(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String clientId) Dedicated JMS broker connection request.
void	onDurableSubscriptionClose(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String clientId, java.lang.String sessionGuid, java.lang.String subscriptionName, java.lang.String topicName) Durable subscription consumer close notification.
boolean	onDurableSubscriptionRequest(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String clientId, java.lang.String sessionGuid, java.lang.String subscriptionName, java.lang.String topicName) Durable subscription request.
void	onMessageConsumerClose(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid, java.lang.String destinationName, boolean destinationIsTopic) Message consumer close notification.
boolean	onMessageConsumerRequest(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid, java.lang.String destinationName, boolean destinationIsTopic) Message consumer creation request.
void	onMessageProducerClose(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid, java.lang.String destinationName, boolean destinationIsTopic) Message producer close notification.
boolean	onMessageProducerRequest(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid, java.lang.String destinationName, boolean destinationIsTopic) Message producer creation request.
java.lang.String	onObjectMessagePayloadClassRequest(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid, java.lang.String destinationName, boolean destinationIsTopic, java.lang.String classFullyQualifiedName) Object message payload class request.
java.lang.Object	onObjectMessagePayloadRequest(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid, java.lang.String destinationName, boolean destinationIsTopic, java.lang.Object payload) Object message payload request.
void	onSessionClose(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid) Session close notification.
void	onSessionOpen(java.lang.String connectionId, java.lang.String jmsConnector, java.lang.String sessionGuid) Session open notification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JmsExtenderHook

public JmsExtenderHook()

Method Detail

init

public void init(java.io.File configDir)
          throws HookException

Hook initialization. Called during the JMS Extender initialization, it is passed the same directory where the JMS Connectors configuration is located.

Parameters:

configDir - the directory where the JMS Connectors configuration is located.

Throws:

HookException - in case the initialization can't complete successfully. In this case the JMS Extender will abort and the Lightstreamer sever will fail the initialization too.

onConnectionRequest

public boolean onConnectionRequest(java.lang.String connectionId,
                          java.lang.String user,
                          java.lang.String password,
                          java.util.Map clientContext,
                          java.lang.String clientPrincipal)
                            throws HookException

User connection and authentication request. Called when a user requests the creation of a connection to the JMS Extender. The connection being authenticated is the Lightstreamer connection between the JMS JS Client and the JMS Extender, and NOT a JMS connection between the JMS Extender and the JMS broker (for which parameters are provided on the JMS Connectors configuration file, see docs). Full client context is passed, together with the client principal when a client certificate is specified. Note that Lightstreamer server must be configured appropriately to receive the client principal (see use_client_auth and force_client_auth parameters). Default implementation simply returns true.

Parameters:

connectionId - the unique identifier of the user's connection.

user - the name of the user trying to connect.

password - the password of the user trying to connect.

clientContext - a key-value map containing properties of the user's request; available keys are:

• "REMOTE_IP" - a string representation of the remote IP related to the current connection; it may be a proxy address.
• "REMOTE_PORT" - string representation of the remote port related to the current connection.
• "USER_AGENT" - the user-agent as declared in the current connection HTTP header.
• "FORWARDING_INFO" - the comma-separated list of addresses forwarded by intermediaries, obtained from the X-Forwarded-For HTTP header, related to the current connection; intermediate proxies usually set this header to supply connection routing information. Note that if the number of forwards to be considered local to the Server environment has been specified through the skip_local_forwards configuration element, in order to better determine the remote address, then these forwards will not be included in the list.
• "LOCAL_SERVER" - the name of the specific server socket that handles the current connection, as configured through the http_server or https_server element.
• "HTTP_HEADERS" - a map object that contains a name-value pair for each header found in the HTTP request that originated the call.

clientPrincipal - the identification name reported in the client TLS/SSL certificate supplied on the socket connection used to issue the request that originated the call; it can be null if client has not authenticated itself or the authentication has failed.

Returns:

true if the user is cleared and the connection can proceed, false if the user must be denied the connection.

Throws:

HookException - in case the authentication can't complete successfully, (the user will be denied the connection).

onConnectionClose

public void onConnectionClose(java.lang.String connectionId)

User connection close notification. Called when a connection to the JMS Extender has been closed. Default implementation does nothing.

Parameters:

connectionId - the unique identifier of the user's connection.

onDedicatedBrokerConnectionRequest

public boolean onDedicatedBrokerConnectionRequest(java.lang.String connectionId,
                                         java.lang.String jmsConnector,
                                         java.lang.String clientId)
                                           throws HookException

Dedicated JMS broker connection request. Called when a user requests a dedicated connection to the JMS broker by specifying a client ID. Gives an opportunity to refuse the dedicated connection. see "Use of durable subscriptions and scalability constraints" in the docs for more informations. Default implementation simply returns true.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying to open a dedicated JMS broker connection on.

clientId - the client ID specified by the user for the JMS broker connection (already mangled and/or decorated by getDedicatedBrokerConnectionName(java.lang.String, java.lang.String, java.lang.String)).

Returns:

true if the dedicated JMS broker connection can proceed, false if the dedicated connection must be denied.

Throws:

HookException - in case of a specific error (the connection will be denied and the exception forwarded to the client).

onSessionOpen

public void onSessionOpen(java.lang.String connectionId,
                 java.lang.String jmsConnector,
                 java.lang.String sessionGuid)

Session open notification. Called when a user creates a new JMS session. Default implementation does nothing.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user opened the session on.

sessionGuid - the GUID of the user's JMS session.

onSessionClose

public void onSessionClose(java.lang.String connectionId,
                  java.lang.String jmsConnector,
                  java.lang.String sessionGuid)

Session close notification. Called when an existing JMS session has been closed. Note that sessions are closed on internal JMS Extender events, not on user request. Default implementation does nothing.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the session was opened on.

sessionGuid - the GUID of the user's JMS session.

onMessageConsumerRequest

public boolean onMessageConsumerRequest(java.lang.String connectionId,
                               java.lang.String jmsConnector,
                               java.lang.String sessionGuid,
                               java.lang.String destinationName,
                               boolean destinationIsTopic)
                                 throws HookException

Message consumer creation request. Called when a user requests the creation of a message consumer. Gives an opportunity to refuse the creation. Note that durable subscriptions are requested through dedicated method onDurableSubscriptionRequest. Default implementation simply returns true.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying to create the consumer on.

sessionGuid - the GUID of the user's JMS session.

destinationName - the name of the destination addressed by the consumer.

destinationIsTopic - true if the destination is a topic.

Returns:

true if the consumer creation can proceed, false if the consumer creation must be denied.

Throws:

HookException - in case of a specific error (the creation will be denied and the exception forwarded to the client).

onMessageConsumerClose

public void onMessageConsumerClose(java.lang.String connectionId,
                          java.lang.String jmsConnector,
                          java.lang.String sessionGuid,
                          java.lang.String destinationName,
                          boolean destinationIsTopic)

Message consumer close notification. Called when a message consumer has been closed. Default implementation does nothing.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the consumer was opened on.

sessionGuid - the GUID of the user's JMS session.

destinationName - the name of the destination addressed by the consumer.

destinationIsTopic - true if the destination is a topic.

onDurableSubscriptionRequest

public boolean onDurableSubscriptionRequest(java.lang.String connectionId,
                                   java.lang.String jmsConnector,
                                   java.lang.String clientId,
                                   java.lang.String sessionGuid,
                                   java.lang.String subscriptionName,
                                   java.lang.String topicName)
                                     throws HookException

Durable subscription request. Called when a user requests a durable subscription. Gives an opportunity to refuse the subscription. Default implementation simply returns true.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying to open the durable subscription on.

clientId - the client ID specified by the user for the JMS connection.

sessionGuid - the GUID of the user's JMS session.

subscriptionName - the name of the durable subscription (already mangled and/or decorated by getDurableSubscriptionName(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String)).

topicName - the name of the topic addressed by the durable subscription.

Returns:

true if the durable subscription can proceed, false if the durable subscription must be denied.

Throws:

HookException - in case of a specific error (the subscription will be denied and the exception forwarded to the client).

onDurableSubscriptionClose

public void onDurableSubscriptionClose(java.lang.String connectionId,
                              java.lang.String jmsConnector,
                              java.lang.String clientId,
                              java.lang.String sessionGuid,
                              java.lang.String subscriptionName,
                              java.lang.String topicName)

Durable subscription consumer close notification. Called when the consumer of a durable subscription has been closed. Note that this does not include the unsubscription of durable subscription. Default implementation does nothing.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user opened the durable subscription on.

clientId - the client ID specified by the user for the JMS connection.

sessionGuid - the GUID of the user's JMS session.

subscriptionName - the name of the durable subscription.

topicName - the name of the topic addressed by the durable subscription.

onMessageProducerRequest

public boolean onMessageProducerRequest(java.lang.String connectionId,
                               java.lang.String jmsConnector,
                               java.lang.String sessionGuid,
                               java.lang.String destinationName,
                               boolean destinationIsTopic)
                                 throws HookException

Message producer creation request. Called when a user requests the creation of a message producer. Gives an opportunity to refuse the creation. Default implementation simply returns true.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying to create the producer on.

sessionGuid - the GUID of the user's JMS session.

destinationName - the name of the destination addressed by the producer.

destinationIsTopic - true if the destination is a topic.

Returns:

true if the producer creation can proceed, false if the producer creation must be denied.

Throws:

HookException - in case of a specific error (the creation will be denied and the exception forwarded to the client).

onMessageProducerClose

public void onMessageProducerClose(java.lang.String connectionId,
                          java.lang.String jmsConnector,
                          java.lang.String sessionGuid,
                          java.lang.String destinationName,
                          boolean destinationIsTopic)

Message producer close notification. Called when a message producer has been closed. Note that producers are closed on internal JMS Extender events, not on user request. Default implementation does nothing.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the producer was opened on.

sessionGuid - the GUID of the user's JMS session.

destinationName - the name of the destination addressed by the producer.

destinationIsTopic - true if the destination is a topic.

onObjectMessagePayloadClassRequest

public java.lang.String onObjectMessagePayloadClassRequest(java.lang.String connectionId,
                                                  java.lang.String jmsConnector,
                                                  java.lang.String sessionGuid,
                                                  java.lang.String destinationName,
                                                  boolean destinationIsTopic,
                                                  java.lang.String classFullyQualifiedName)
                                                    throws HookException

Object message payload class request. Called when a user requests to send an object message, before the payload class is initialized. Gives an opportunity to refuse sending the message or altering the payload class. Default implementation simply returns the value of classFullyQualifiedName.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying

sessionGuid - the GUID of the user's JMS session.

destinationName - the name of the destination addressed by the producer.

destinationIsTopic - true if the destination is a topic.

classFullyQualifiedName - requested fully qualified name of the class for the object message payload.

Returns:

the name of the class accepted for the object message payload (may be different than the requested one).

Throws:

HookException - in case of a specific error (the request will be denied and the exception forwarded to the client).

onObjectMessagePayloadRequest

public java.lang.Object onObjectMessagePayloadRequest(java.lang.String connectionId,
                                             java.lang.String jmsConnector,
                                             java.lang.String sessionGuid,
                                             java.lang.String destinationName,
                                             boolean destinationIsTopic,
                                             java.lang.Object payload)
                                               throws HookException

Object message payload request. Called when a user requests to send an object message, after the payload class is initialized, instantiated and filled with the user content. Gives an opportunity to refuse sending the message or altering the payload. Default implementation simply returns the value of payload.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying

sessionGuid - the GUID of the user's JMS session.

destinationName - the name of the destination addressed by the producer.

destinationIsTopic - true if the destination is a topic.

payload - requested object message payload.

Returns:

the accepted payload for the object message (may be different than the requested one).

Throws:

HookException - in case of a specific error (the request will be denied and the exception forwarded to the client).

getDedicatedBrokerConnectionName

public java.lang.String getDedicatedBrokerConnectionName(java.lang.String connectionId,
                                                java.lang.String jmsConnector,
                                                java.lang.String clientId)

Dedicated JMS broker connection name mangling or decoration function. Called when a user requests a dedicated connection to the JMS broker by specifying a client ID. Gives an opportunity to mangle and/or decorate the client ID specified to ensure ID uniqueness per user (see "Use of durable subscriptions and scalability constraints" in the docs). Please note that the connection ID may change unexpectedly and should not be used as part of the name mangling/decoration. Note also that this method may be called more than once for the same broker connection, in this case the mangled/decorated name should always be the same. Default implementation simply returns the specified client ID.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying to open a dedicated JMS broker connection on.

clientId - the client ID specified by the user for the JMS broker connection.

Returns:

the clientID that must be used for the JMS broker connection.

getDurableSubscriptionName

public java.lang.String getDurableSubscriptionName(java.lang.String connectionId,
                                          java.lang.String jmsConnector,
                                          java.lang.String clientId,
                                          java.lang.String sessionGuid,
                                          java.lang.String subscriptionName,
                                          java.lang.String topicName)

Durable subscription name mangling or decoration function. Called when a user requests a durable subscription to the JMS broker. Gives an opportunity to mangle and/or decorated the specified subscription name to ensure name uniqueness per user (see "Use of durable subscriptions and scalability constraints" in the docs). Please note that the connection ID may change unexpectedly and should not be used as part of the name mangling/decoration. Note also that this method may be called more than once for the same subscription, in this case the mangled/decorated name should always be the same. Default implementation simply returns the specified subscription name.

Parameters:

connectionId - the unique identifier of the user's connection.

jmsConnector - the name of the JMS Connector the user is trying to open the durable subscription on.

clientId - the client ID specified by the user for the JMS connection.

sessionGuid - the GUID of the user's JMS session.

subscriptionName - the name of the durable subscription specified by the client.

topicName - the name of the topic addressed by the durable subscription.

Returns:

the subscription name that must be used for the durable subscription.