org.systinet.transport.jms
Interface Reduction

All Known Implementing Classes:

ReductionTemplate

public interface Reduction

This interface provides an access to JMS objects needed by JMS transport. Implementations should access the objects in provider-specific way. It's responsible for receiving and sending JMS messages on both server and client sides.

It's on the responsibility of the reduction to add support for coupling of JMS messages. It's common to use JMS string property with name JmsConstants.MSG_CALL_ID to transfer the coupling information. Only messages sent over JMS queues can couple and can simulate the synchronous transport.

The methods responsible to send or publish messages (sendClientData and publishClientData) on the client side should transform all properties got as jmsProperties to the properties of the JMS message. Moreover, they must set the string property with the name JmsConstants.MSG_TYPE to value JmsConstants.TYPE_REQUEST, set the JMS int property JmsConstants.CALL_METHOD according to the property with the same name and sendClientData should set the string property with the name JmsConstants.MSG_CALLID or JMS correlation ID to value, which is unique for the optional request - response pair. It should also take JmsConstanst.SERVER_SELECTOR value from the jmsProperties and store it to use for selection in the optional call of the method method receiveData.

On the server side, the listening methods startQueueListening and startTopicListening should listen using the selector, which selects messages where JmsConstants.MSG_TYPE propety equals to JmsConstants.TYPE_REQUEST and if server selector is set, JmsConstants.SERVER_SELECTOR equals to the value of their serverSelector parameter. When a meesage is received, these methods should also create output properties, where they store the state information like call id of the received message. The output properties must also contain property with the name JmsConstants.CALL_METHOD and Integer value set according to the JMS property with the same name. Optionaly it should try to get JMS property and set the property in the properties map with names :

• JmsConstants.MSG_HDR
• JmsConstants.MSG_CLIENT_ADDRESS
• JmsConstants.MSG_CLIENT_URI_PORT
• JmsConstants.MSG_CLIENT_URI_USERINFO
• JmsConstants.MSG_CLIENT_URI_USERINFO
• JmsConstants.MSG_CLIENT_URI_PATH
• JmsConstants.MSG_CLIENT_URI_FRAGMENT
• JmsConstants.MSG_CLIENT_URI_QUERY
• JmsConstants.MSG_CLIENT_URI_REPLY_NAME
• JmsConstants.MSG_SC

They pass the properties to the method JmsDataHandler.processData along with data it receives. JMS transport guarantees, that all these properties will get the server side method sendData.

When sending the message back on the server side (possible only when using queues), the method sendData should transform all properties passed as outputProperties parameter to the JMS ones. When sending the message, priority and timeToLive parameters should be applied too.

On the client side, data are received by receiveClientData method. It can blocks until data arrives and it can use aditional data initialized in previous sendClientData and publishClientData method calls. It should select messages using server selector and call id values and convert JMS property with name JmsConstants.MSG_HDR to properties.

Since:

4.5

See Also:

JmsConstants, JmsDataHandler

Component:

J2EE-JMS-Transport

Method Summary

boolean	check() Determines, whether this reduction can be used.
void	publishClientData(javax.jms.TopicSession session, javax.jms.Topic topic, byte[] data, java.util.Map jmsProperties, int deliveryMode, int priority, int timeToLive) This method publishes data using the topic session and the topic.
byte[]	receiveClientData(javax.jms.QueueSession session, javax.jms.Queue queue, long timeout, java.util.Map properties) Receives data using the queue and session.
javax.jms.Queue	resolveQueue(java.lang.String name) Resolves the queue with the given name
javax.jms.QueueConnectionFactory	resolveQueueConnectionFactory(java.lang.String name) Resolves the queue connection factory with the given name
javax.jms.Topic	resolveTopic(java.lang.String name) Resolves the topic with the given name
javax.jms.TopicConnectionFactory	resolveTopicConnectionFactory(java.lang.String name) Resolves the topic connection factory with the given name
void	sendClientData(javax.jms.QueueSession session, javax.jms.Queue queue, javax.jms.Queue replyQueue, byte[] data, java.util.Map jmsProperties, int deliveryMode, int priority, int timeToLive) Sends data using the queue and session.
void	sendData(javax.jms.QueueSession session, javax.jms.Queue queue, byte[] data, java.util.Map outputProperties, int deliveryMode, int priority, int timeToLive) Sends an output message on the server side.
void	startQueueListening(JmsDataHandler handler, javax.jms.QueueSession session, javax.jms.Queue queue, java.lang.String serverSelector) Typicaly, this method calls server side part of the JMS transport when it starts listening.
void	startResolving(java.util.Map properties) Called when the first resolve* method is going to be called after the reduction was instantiated or the method stopResolving was closed.
void	startTopicListening(JmsDataHandler handler, javax.jms.TopicSession session, javax.jms.Topic topic, java.lang.String serverSelector, java.lang.String durableId) Typicaly, this method calls server side part of the JMS transport when it starts listening.
void	stopListening() Stops listening and frees resources allocated for this server side reduction
void	stopResolving() Called after the last resolve* method call.

Method Detail

startResolving

public void startResolving(java.util.Map properties)
                    throws javax.naming.NamingException

Called when the first resolve* method is going to be called after the reduction was instantiated or the method stopResolving was closed. Typicaly, it creates a new InitialContext.

Parameters:

properties - allows passing of customization parameters to the reduction implementation. User may pass them using WebserviceLookup.lookup(...). Otherwise, the properties are read from JMS transport configuration.

Throws:

javax.naming.NamingException

stopResolving

public void stopResolving()
                   throws javax.naming.NamingException

Called after the last resolve* method call. Typicaly, it closes and unsets the InitialContext.

Throws:

javax.naming.NamingException

check

public boolean check()

Determines, whether this reduction can be used.

Returns:

true if the reduction can be used, typicaly when its requirements are fulfiled, JMS provider classes can be found in the classpath etc. otherwise it returns false. The first resovled reduction will be used to process JMS messaging.

resolveQueue

public javax.jms.Queue resolveQueue(java.lang.String name)
                             throws javax.naming.NamingException

Resolves the queue with the given name

Parameters:

name - of the queue

Returns:

the queue

Throws:

javax.naming.NamingException

resolveTopic

public javax.jms.Topic resolveTopic(java.lang.String name)
                             throws javax.naming.NamingException

Resolves the topic with the given name

Parameters:

name - of the topic

Returns:

the topic

Throws:

javax.naming.NamingException

resolveQueueConnectionFactory

public javax.jms.QueueConnectionFactory resolveQueueConnectionFactory(java.lang.String name)
                                                               throws javax.naming.NamingException

Resolves the queue connection factory with the given name

Parameters:

name - of the queue connection factory

Returns:

the QueueConnectionFactory

Throws:

javax.naming.NamingException

resolveTopicConnectionFactory

public javax.jms.TopicConnectionFactory resolveTopicConnectionFactory(java.lang.String name)
                                                               throws javax.naming.NamingException

Resolves the topic connection factory with the given name

Parameters:

name - of the topic connection factory

Returns:

the TopicConnectionFactory

Throws:

javax.naming.NamingException

sendClientData

public void sendClientData(javax.jms.QueueSession session,
                           javax.jms.Queue queue,
                           javax.jms.Queue replyQueue,
                           byte[] data,
                           java.util.Map jmsProperties,
                           int deliveryMode,
                           int priority,
                           int timeToLive)
                    throws javax.jms.JMSException

Sends data using the queue and session. This method should also add necessary coupling information and set correct JMS properties. This method is used by client side of the JMS transport. It must store coupling information which can be reused by the method receiveClientData. The method must set coupling information to the message and set message selector property, if it's not null. The value of the message selector key is JmsConstants.SERVER_SELECTOR and the value should be obtained from jmsProperties : String serverSelector = (String)jmsProperties.get(JmsConstants.SERVER_SELECTOR)

Parameters:

session - the session to be used when sending the message

queue - the queue to be used when sending the message

replyQueue - the queue where this reduction should expect optional response data. May be null.

data - data to be sent. The method may perform aditional processing like encrypting or encoding the data.

jmsProperties - the JMS properties to be set ob the output message. The method may perform aditional processing on othe properies.

deliveryMode - delivery mode to be set, one of javax.jms.DeliveryMode constants

priority - priority of the message

timeToLive - time to live of the message

Throws:

javax.jms.JMSException

receiveClientData

public byte[] receiveClientData(javax.jms.QueueSession session,
                                javax.jms.Queue queue,
                                long timeout,
                                java.util.Map properties)
                         throws javax.jms.JMSException

Receives data using the queue and session. This method reuses coupling information created by the previous call of the method sendClientData. It is used by the client side of the JMS transport. The selection of receive messages whould be filtered by the selector : String selector = JmsConstants.MSG_TYPE + "='" + JmsConstants.TYPE_REQUEST + "'" + ( ( serverSelector == null ) ? "" : ( " AND " + JmsConstants.SERVER_SELECTOR + "='" + serverSelector + "'" ) ); The selector value can be obtained from the properties parameter this way : String serverSelector = (String)outputProperties.get(JmsConstants.SERVER_SELECTOR)

Parameters:

session - the session to be used when receiving the message

queue - the queue to be used when receiving the message

timeout - time, after timeout occures

properties - the structure to be filled with received properties and it initialy contains some properties like server selector value used to receive message

Returns:

the data. The method may perform aditional processing like decrypting or decoding the data.

Throws:

javax.jms.JMSException

publishClientData

public void publishClientData(javax.jms.TopicSession session,
                              javax.jms.Topic topic,
                              byte[] data,
                              java.util.Map jmsProperties,
                              int deliveryMode,
                              int priority,
                              int timeToLive)
                       throws javax.jms.JMSException

This method publishes data using the topic session and the topic. The method shouldn't add any coupling information, because JMS transport doesn't support synchronous operations over JMS topics. The method must set coupling information to the message and set message selector property, if it's not null. The value of the message selector key is JmsConstants.SERVER_SELECTOR and the value should be obtained from jmsProperties : String serverSelector = (String)jmsProperties.get(JmsConstants.SERVER_SELECTOR)

Parameters:

session - the session to be used when publishing the message

topic - the topic to be used when publishing the message

data - data to be sent. The method may perform aditional processing like encrypting or encoding the data.

jmsProperties - the JMS properties to be set ob the output message. The method may perform aditional processing on othe properies.

deliveryMode - delivery mode to be set, one of javax.jms.DeliveryMode constants

priority - priority of the message

timeToLive - time to live of the message

Throws:

javax.jms.JMSException

startQueueListening

public void startQueueListening(JmsDataHandler handler,
                                javax.jms.QueueSession session,
                                javax.jms.Queue queue,
                                java.lang.String serverSelector)
                         throws javax.jms.JMSException

Typicaly, this method calls server side part of the JMS transport when it starts listening. The responsibility of this method is to decode data and call processData on the handler when a new message arrives. Typicaly, it will call either session.setMessageListener or session.createReceiver(queue) to receive data. Before it delivers data and JMS properties to the handler, it may perform aditional decoding, decrypting etc. If this method is called, startTopicListening won't be called and the reduction is a queue type. After data are received, invoke the method JmsDataHandler.processData(byte[],Map,Map,Reduction,javax.jms.Destination)

Parameters:

handler - the handler to be used to process received data

session - the session which receives the data

queue - the queue which receives the data

serverSelector - id which identifies messages sent to the server. If not null, the listening must be performed with the selector string : String selector = JmsConstants.MSG_TYPE + "='" + JmsConstants.TYPE_REQUEST + "'" + ( ( serverSelector == null ) ? "" : ( " AND " + JmsConstants.SERVER_SELECTOR + "='" + serverSelector + "'" ) );

Throws:

javax.jms.JMSException

startTopicListening

public void startTopicListening(JmsDataHandler handler,
                                javax.jms.TopicSession session,
                                javax.jms.Topic topic,
                                java.lang.String serverSelector,
                                java.lang.String durableId)
                         throws javax.jms.JMSException

Typicaly, this method calls server side part of the JMS transport when it starts listening. The responsibility of this method is to decode data and call processData on the handler when a new message arrives. Typicaly, it will call either session.setMessageListener or session.createSubscriber(topic) to receive data. Before it delivers data and JMS properties to the handler, it may perform aditional decoding, decrypting etc. If this method is called, startQueueListening won't be called and the reduction is a topic type.

Parameters:

handler - the handler to be used to process received data

session - the session which receives the data

topic - the topic which receives the data

serverSelector - id which identifies messages sent to the server. If not null, the listening must be performed with the selector string : String selector = JmsConstants.MSG_TYPE + "='" + JmsConstants.TYPE_REQUEST + "'" + ( ( serverSelector == null ) ? "" : ( " AND " + JmsConstants.SERVER_SELECTOR + "='" + serverSelector + "'" ) );

durableId - the client identifier of the durable subscription. If null, the subscriber will not be durable.

Throws:

javax.jms.JMSException

stopListening

public void stopListening()

Stops listening and frees resources allocated for this server side reduction

sendData

public void sendData(javax.jms.QueueSession session,
                     javax.jms.Queue queue,
                     byte[] data,
                     java.util.Map outputProperties,
                     int deliveryMode,
                     int priority,
                     int timeToLive)
              throws javax.jms.JMSException

Sends an output message on the server side. The only state information it can use are output properties, which it sets to the JMS message it creates and sends. It's called on the server side of the JMS transport. There's no topic equivalent of this method because topics can be used only in one-way operations. The method must set coupling information to the message and set message selector property, if it's not null. The value of the message selector key is JmsConstants.SERVER_SELECTOR and the value should be obtained from jmsProperties : String serverSelector = (String)outputProperties.get(JmsConstants.SERVER_SELECTOR)

Parameters:

session - the session, which sends data

queue - the queue, which sends data

data - the data to be sent

outputProperties - JMS properties which have to be set on the output JMS message.

deliveryMode - delivery mode to be set, one of javax.jms.DeliveryMode constants

priority - priority of the message

timeToLive - time to live of the message

Throws:

javax.jms.JMSException