org.jumpi.impl.connector.jms10
Class JmsConnector

java.lang.Object
  |
  +--org.jumpi.impl.AbstractConnector
        |
        +--org.jumpi.impl.connector.jms10.JmsConnector

All Implemented Interfaces:

Component, Configurable, Connector, Manageable, java.lang.Runnable, Task

public class JmsConnector

extends AbstractConnector

The JmsConnector allows message sending and receiving via a third-party JMS provider. The JmsConnector is JMS provider agnostic and uses portable client JMS code, using JNDI lookups for ConnectionFactories and Destinations. The JmsConnector uses separate JNDI Contexts for Topic and Queues. One QueueConnection and one TopicConnection are created on demand for messaging in the point-to-point or publish-subscribe domain respectively. Messaging to separate JmsDestinations is performed in separate JMS Sessions. One JMS Producer is created per JmsDestination to perform message sending. One JMS Consumer is created per JmsDestination to preform message receiving. Send receive and request reply messaging is possible.

The syntax of a JmsDestination is:

<protocolname>://topic|queue:<name>

Field Summary

Fields inherited from class org.jumpi.impl.AbstractConnector

cancelledRecvs_, cancelledSends_, controller_, joinFailInterval_, joinTestInterval_, jumpi_, maxRecvBacklog_, maxSendBacklog_, name_, protocol_, recvQueue_, recvTransformer_, sendQueue_, sendTransformer_, started_, stopping_, taskId_, url_format_, url_prefix_

Constructor Summary

JmsConnector()

Method Summary

void	cancelRecv(Envelope env) Does nothing.
void	cancelSend(Envelope env) Does nothing.
protected boolean	checkJoinCondition() The shutdown join condition is true if there are no active JMS Contexts.
void	configure(java.lang.String name, Properties props) Configure the JmsConnector.
Destination	getDestination(java.lang.String url, java.util.Hashtable clientProps) Get the Destination corresponding to the Url provided.
void	manage(Component root, Component parent, java.lang.String operation, java.util.Hashtable parameters) Perform a recursive management operation through the Jumpi component tree, using the parameters provided.
protected boolean	onRecv(Envelope env) Receive a message from a JMS Destination.
protected boolean	onSend(Envelope env) Send a message to a JMS Destination.
void	recv(Envelope env) Perform the recv synchronously.
void	send(Envelope env) Perform the send synchronously.
protected void	shutdownState() Clear the JMSContext cache and close any active JMS Contexts.

Methods inherited from class org.jumpi.impl.AbstractConnector

getName, getTaskId, isLongRunning, isSchedulable, run

Methods inherited from class java.lang.Object

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

Constructor Detail

JmsConnector

public JmsConnector()

Method Detail

configure

public void configure(java.lang.String name,
                      Properties props)
               throws java.lang.Exception

Configure the JmsConnector.

The following configuration attributes are defined in addition to those of the superclass:

• queuejndikey<N> - string - optional.

  The key for the N-th JNDI InitialContext's property for Queues. The value is the property queuejndivalue<N>.

• queuejndivalue<N> - string - optional[].

  The value for the N-th JNDI InitialContext's property for Queues. The value is the property queuejndikey<N>.

• topicjndikey<N> - string - optional.

  The key for the N-th JNDI InitialContext's property for Topics. The value is the property topicjndivalue<N>.

• topicjndivalue<N> - string - optional[].

  The value for the N-th JNDI InitialContext's property for Topics. The value is the property topicjndikey<N>.

• jndiqueueconnectionfactorylookup - string - optional[QueueConnectionFactory].

  The value used to lookup the QueueConnectionFactory in JNDI for the single JMS Connection used for point-to-point messaging.

• jnditopicconnectionfactorylookup - string - optional[TopicConnectionFactory].

  The value used to lookup the TopicConnectionFactory in JNDI for the single JMS Connection used for publish subscribe messaging.

Specified by:

configure in interface Configurable

Overrides:

configure in class AbstractConnector

Parameters:

name - the fully qualified instance name.

props - the read-only properties to configure the instance with.

Throws:

java.lang.Exception - when configuration is unsuccessful.

manage

public void manage(Component root,
                   Component parent,
                   java.lang.String operation,
                   java.util.Hashtable parameters)
            throws java.lang.Exception

Perform a recursive management operation through the Jumpi component tree, using the parameters provided.

• STARTUP. Establish the JNDI Initial Contexts to use for later JMS instance lookups.

Specified by:

manage in interface Manageable

Overrides:

manage in class AbstractConnector

Parameters:

root - the Jumpi instance at the root of the component tree.

parent - the immediate parent of the component.

operation - the operation.

parameters - the operation parameters.

Throws:

java.lang.Exception - if any failure to perform management occurs.

checkJoinCondition

protected boolean checkJoinCondition()

The shutdown join condition is true if there are no active JMS Contexts.

Specified by:

checkJoinCondition in class AbstractConnector

Returns:

true if there are no pending send or receive operations.

shutdownState

protected void shutdownState()

Clear the JMSContext cache and close any active JMS Contexts.

Specified by:

shutdownState in class AbstractConnector

getDestination

public Destination getDestination(java.lang.String url,
                                  java.util.Hashtable clientProps)

Get the Destination corresponding to the Url provided.

Specified by:

getDestination in interface Connector

Overrides:

getDestination in class AbstractConnector

Parameters:

url - the Url of a JMS Topic or Queue.

clientProps - not used.

Returns:

a Destination if the Url corresponds to a valid JMS Destination, otherwise null.

Throws:

java.lang.IllegalArgumentException - when url is null.

onSend

protected boolean onSend(Envelope env)
                  throws java.lang.Exception

Send a message to a JMS Destination.

The message format passed over JMS is an ObjectMessage. The ObjectMessage payload is simply a serializable Object. Transformation of the message to send by the send transformer is optional.

Allows multiple concurrent send operations to different Destinations but not the same Destination.

The JMS provider's send operation may or may not be truly asynchronous. The send is considered complete on the synchronous return from the JMS provider's send or publish call. This may block due to flow control in the JMS provider.

The PROPERTY_JMS_CORRELATION_ID is used to enable correlation of reply messages with request messages. The property is transferred unchanged to the JMS Message's JMSCorrelationID.

The PROPERTY_JMS_TTL is the time-to-live in milliseconds for sent messages. If not set, messages never expire.

The PROPERTY_JMS_REPLY_WANTED is an indicator that the sender is a requestor and will perform a receive on the Destination returned in the PROPERTY_JMS_REPLY_DESTINATION which is returned in the send operation's Handle's properties. The JmsConnector creates a Temporary JMS Destination which is set as the JMS Message's JMSReplyTo Destination. Use the PROPERTY_JMS_CORRELATION_ID to give the replyer a correlation id to use on the reply, so the requestor can uniquely receive the reply.

Specified by:

onSend in class AbstractConnector

Parameters:

env - the Envelope containing the Destination to send to and the message.

Returns:

true on success, else false on managed failure.

Throws:

java.lang.Exception - if a failure condition occurs.

send

public void send(Envelope env)
          throws java.lang.Exception

Perform the send synchronously.

Specified by:

send in interface Connector

Overrides:

send in class AbstractConnector

Parameters:

env - the Envelope which gives the Destination to send to and the message itself.

Throws:

java.lang.Exception - if any failure condition occurs during the send method.

java.lang.IllegalArgumentException - when env is null.

java.lang.IllegalStateException - when not started or stopping.

See Also:

Controller.callbackSend(org.jumpi.spi.Envelope, boolean, java.lang.String)

cancelSend

public void cancelSend(Envelope env)

Does nothing.

Specified by:

cancelSend in interface Connector

Overrides:

cancelSend in class AbstractConnector

Parameters:

env - the send operation's Envelope to cancel.

onRecv

protected boolean onRecv(Envelope env)
                  throws java.lang.Exception

Receive a message from a JMS Destination. The time to block in the receive is configurable. If the JMS Message received was sent with a correlation id, then this is provided to the client layer in the Handle's properties called PROPERTY_JMS_CORRELATION_ID. If the JMS Message received has a JMSReplyTo Destination set for replying, then this Destination is returned to the client layer in the Handle's sender. If no JMSReplyTo is set on the received message then the receive Destination is the Sender.

The receive operation at the JMS layer delivers expects ObjectMessages. If a receive transformer is configured, then this must transform the ObjectMessage.

Allows multiple concurrent recv operations to different Destinations but not the same Destination.

The JMS provider's receive operation is synchronous, blocking for at most for the period defined in the PROPERTY_JMS_RECEIVE_TIMEOUT. The receive is considered complete on the synchronous return from the JMS provider's receive call. If a receive timeout happens, then the receive operation is failed.

The PROPERTY_JMS_RECEIVE_TIMEOUT is the time in milliseconds for the receive to block without receiving a message. If not set, receives block forever.

The PROPERTY_JMS_CORRELATION_ID is used to enable correlation of reply messages with request messages. The JMS Message's JMSCorrelationID must match the given property for a receive to be matched. Unmatched received messages are simply discarded!

Specified by:

onRecv in class AbstractConnector

Parameters:

env - the Envelope containing the Destination to receive from.

Returns:

true on success, or false on a managed failure, i.e. read timeout.

Throws:

java.lang.Exception - if a failure condition occurs.

recv

public void recv(Envelope env)
          throws java.lang.Exception

Perform the recv synchronously.

Specified by:

recv in interface Connector

Overrides:

recv in class AbstractConnector

Parameters:

env - the Envelope which gives the Destination to receive from and where the received message is eventually placed with the sender.

Throws:

java.lang.Exception - if any failure condition occurs during the recv method.

java.lang.IllegalArgumentException - when env is null.

java.lang.IllegalStateException - when not started or stopping.

See Also:

Controller.callbackRecv(org.jumpi.spi.Envelope, boolean, java.lang.String)

cancelRecv

public void cancelRecv(Envelope env)

Does nothing.

Specified by:

cancelRecv in interface Connector

Overrides:

cancelRecv in class AbstractConnector

Parameters:

env - the recv operation's Envelope to cancel.