Jumpi v1.2.0

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:

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.

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.

Jumpi v1.2.0

Copyright 2003, Peter Jonathan Klauser.