org.fcrepo.server.messaging
Class JMSManager

java.lang.Object
  org.fcrepo.server.messaging.JMSManager

public class JMSManager
extends Object

The JMSManager class is a facade in that it provides a very simple interface for using JMS. Whether a destination is a topic or queue is hidden as an implementation detail. Adapted from code originally written by Eric J. Bruno.

Since:

3.0

Version:

$Id$

Author:

Eric J. Bruno, Edwin Shin, Bill Branan

Nested Class Summary

static class

JMSManager.DestinationType

Field Summary

protected boolean	connected
protected javax.jms.Connection	connection
static String	CONNECTION_FACTORY_NAME Connection Factory Lookup Name
protected Map<String,javax.jms.MessageConsumer>	durableSubscriptions
protected Hashtable<String,org.fcrepo.server.messaging.JMSManager.JMSDestination>	jmsDestinations
protected Context	jndi

Constructor Summary

JMSManager(Properties jndiProps)
Creates a JMS manager using jndi properties to start a connection to a JMS provider.

JMSManager(Properties jndiProps, String clientId)
Creates a JMS manager using jndi properties to start a connection to a JMS provider.

Method Summary

void	close()
protected void	connectToJMS(String clientId)
javax.jms.BytesMessage	createBytesMessage(String destName)
javax.jms.Destination	createDestination(String name, JMSManager.DestinationType type) Creates a Destination.
javax.jms.Destination	createDestination(String name, JMSManager.DestinationType type, boolean fTransacted, int ackMode) Creates a Destination if the Destination has not already been created.
protected javax.jms.Message	createJMSMessage(Serializable obj, javax.jms.Session session)
javax.jms.MapMessage	createMapMessage(String destName)
javax.jms.ObjectMessage	createObjectMessage(String destName, Serializable object)
javax.jms.TextMessage	createTextMessage(String destName, String text)
protected javax.jms.Connection	getConnection()
javax.jms.MessageConsumer	getConsumer(String destName)
protected Context	getContext()
JMSManager.DestinationType	getDefaultDestinationType()
javax.jms.Destination	getDestination(String destName) Gets the named Destination if it has been created.
List<javax.jms.Destination>	getDestinations() Provides a listing of the currently available destinations
protected org.fcrepo.server.messaging.JMSManager.JMSDestination	getJMSDestination(String name)
javax.jms.MessageProducer	getProducer(String destName)
javax.jms.Session	getSession(String destName)
protected Object	jndiLookup(String name)
javax.jms.Message	listen(javax.jms.Destination dest) Convenience method for synchronous listen with no message selector
void	listen(javax.jms.Destination dest, javax.jms.MessageListener callback) This is an asynchronous listen.
javax.jms.Message	listen(javax.jms.Destination dest, String messageSelector) This is a synchronous listen.
void	listen(javax.jms.Destination dest, String messageSelector, javax.jms.MessageListener callback) This is an asynchronous listen.
javax.jms.Message	listen(String destName) Convenience method for synchronous listen with no message selector
javax.jms.Message	listen(String destName, int timeout) Convenience method for synchronous listen with no message selector
void	listen(String destName, javax.jms.MessageListener callback) Convenience method for asynchronous listen with no message selector
javax.jms.Message	listen(String destName, String messageSelector) This is a synchronous listen.
javax.jms.Message	listen(String destName, String messageSelector, int timeout) This is a synchronous listen.
void	listen(String destName, String messageSelector, javax.jms.MessageListener callback) This is an asynchronous listen.
String	listenDurable(String topic, javax.jms.MessageListener callback)
String	listenDurable(String topicName, javax.jms.MessageListener callback, String subscriptionName)
String	listenDurable(javax.jms.Topic topic, javax.jms.MessageListener callback) This is a convenience method to allow a durable subscription to be created using the topic as the subscription name.
String	listenDurable(javax.jms.Topic topic, String messageSelector, javax.jms.MessageListener callback, String subscriptionName) This is an asynchronous and durable listen.
void	send(javax.jms.Destination dest, javax.jms.Message msg) Allows the caller to send a Message object to a destination
void	send(String destName, javax.jms.Message msg) Allows the caller to send a Message object to a named destination
void	send(String destName, Serializable obj) Allows the caller to send a Serializable object to a destination
void	send(String destName, String messageText) Allows the caller to send text to a destination
void	setDefaultDestinationType(JMSManager.DestinationType defaultDestinationType) Sets the default DestinationType
protected void	setupAsynchConsumer(org.fcrepo.server.messaging.JMSManager.JMSDestination jmsDest, String messageSelector, javax.jms.MessageListener callback)
protected void	setupProducer(org.fcrepo.server.messaging.JMSManager.JMSDestination jmsDest)
protected javax.jms.Message	setupSynchConsumer(org.fcrepo.server.messaging.JMSManager.JMSDestination jmsDest, String messageSelector, int timeout)
void	stop(String destName) Stops producers and consumers on a given destination.
void	stopDurable(String subscriptionName) Stops a durable message consumer.
void	unsubscribeAllDurable() Removes all durable topic subscriptions created using this JMSManager instance
void	unsubscribeDurable(String subscriptionName) Removes the durable subscription with the given name.

Methods inherited from class java.lang.Object

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

Field Detail

CONNECTION_FACTORY_NAME

public static final String CONNECTION_FACTORY_NAME

Connection Factory Lookup Name

See Also:

Constant Field Values

jndi

protected Context jndi

connection

protected javax.jms.Connection connection

connected

protected boolean connected

jmsDestinations

protected Hashtable<String,org.fcrepo.server.messaging.JMSManager.JMSDestination> jmsDestinations

durableSubscriptions

protected Map<String,javax.jms.MessageConsumer> durableSubscriptions

Constructor Detail

JMSManager

public JMSManager(Properties jndiProps)
           throws MessagingException

Creates a JMS manager using jndi properties to start a connection to a JMS provider. If jndi properties are null an attempt will be made to create a connection based on a java:comp/env context

Parameters:

jndiProps -

Throws:

MessagingException

JMSManager

public JMSManager(Properties jndiProps,
                  String clientId)
           throws MessagingException

Creates a JMS manager using jndi properties to start a connection to a JMS provider. If jndi properties are null an attempt will be made to create a connection based on a java:comp/env context A connection must have a clientId in order to create durable subscriptions. This clientId can either be set administratively on the Connection object created in the JNDI store or by providing a non-null value for the clientId parameter of this method.

Parameters:

jndiProps -

clientId -

Throws:

MessagingException

Method Detail

createDestination

public javax.jms.Destination createDestination(String name,
                                               JMSManager.DestinationType type)
                                        throws MessagingException

Creates a Destination. This is a convenience method which is the same as calling: createDestination(name, type, false, Session.AUTO_ACKNOWLEDGE)

Throws:

MessagingException

createDestination

public javax.jms.Destination createDestination(String name,
                                               JMSManager.DestinationType type,
                                               boolean fTransacted,
                                               int ackMode)
                                        throws MessagingException

Creates a Destination if the Destination has not already been created.

Parameters:

name - - the name of the destination to create

type - - the destination type (topic or queue)

fTransacted - - determines whether the session will maintain transactions

ackMode - - determines the session acknowledgment mode

Throws:

MessagingException

listen

public javax.jms.Message listen(String destName)
                         throws MessagingException

Convenience method for synchronous listen with no message selector

Throws:

MessagingException

See Also:

listen(String, String)

listen

public javax.jms.Message listen(String destName,
                                String messageSelector)
                         throws MessagingException

This is a synchronous listen. The caller will block until a message is received for the given destination. Messages will be filtered based on the provided message selector.

Parameters:

destName - the Destination to listen on

messageSelector - selection criteria for filtering messages

Returns:

the Message received for the given Destination

Throws:

Exception

MessagingException

listen

public javax.jms.Message listen(javax.jms.Destination dest)
                         throws MessagingException

Convenience method for synchronous listen with no message selector

Throws:

MessagingException

See Also:

listen(Destination, String)

listen

public javax.jms.Message listen(javax.jms.Destination dest,
                                String messageSelector)
                         throws MessagingException

This is a synchronous listen. The caller will block until a message is received for the given destination. Messages will be filtered based on the provided message selector.

Parameters:

dest - the Destination to listen on

messageSelector - selection criteria for filtering messages

Returns:

the Message received for the given Destination

Throws:

Exception

MessagingException

listen

public javax.jms.Message listen(String destName,
                                int timeout)
                         throws MessagingException

Convenience method for synchronous listen with no message selector

Throws:

MessagingException

See Also:

listen(String, String, int)

listen

public javax.jms.Message listen(String destName,
                                String messageSelector,
                                int timeout)
                         throws MessagingException

This is a synchronous listen. The caller will block until a message is received for the given destination OR the timeout value (in milliseconds) has been reached. Messages will be filtered based on the provided message selector.

Parameters:

destName - the Destination to listen on

messageSelector - selection criteria for filtering messages

timeout - time in milliseconds before timing out

Returns:

the Message received for the given Destination

Throws:

Exception

MessagingException

listen

public void listen(String destName,
                   javax.jms.MessageListener callback)
            throws MessagingException

Convenience method for asynchronous listen with no message selector

Throws:

MessagingException

See Also:

listen(String, String, MessageListener)

listen

public void listen(String destName,
                   String messageSelector,
                   javax.jms.MessageListener callback)
            throws MessagingException

This is an asynchronous listen. The caller provides a JMS callback interface reference, and any messages received for the given destination are provided through the onMessage() callback method Messages will be filtered based on the provided message selector.

Throws:

MessagingException

listen

public void listen(javax.jms.Destination dest,
                   javax.jms.MessageListener callback)
            throws MessagingException

This is an asynchronous listen. The caller provides a JMS callback interface reference, and any messages received for the given destination are provided through the onMessage() callback method.

Throws:

MessagingException

listen

public void listen(javax.jms.Destination dest,
                   String messageSelector,
                   javax.jms.MessageListener callback)
            throws MessagingException

This is an asynchronous listen. The caller provides a JMS callback interface reference, and any messages received for the given destination are provided through the onMessage() callback method. Messages will be filtered based on the provided message selector.

Throws:

MessagingException

listenDurable

public String listenDurable(String topic,
                            javax.jms.MessageListener callback)
                     throws MessagingException

Throws:

MessagingException

See Also:

listenDurable(Topic, MessageListener)

listenDurable

public String listenDurable(String topicName,
                            javax.jms.MessageListener callback,
                            String subscriptionName)
                     throws MessagingException

Throws:

MessagingException

See Also:

JMSManager#listenDurable(Topic, MessageListener, String)

listenDurable

public String listenDurable(javax.jms.Topic topic,
                            javax.jms.MessageListener callback)
                     throws MessagingException

This is a convenience method to allow a durable subscription to be created using the topic as the subscription name. Calling this method is the same as calling listenDurable(topic, "", callback, null)

Throws:

MessagingException

See Also:

JMSManager#listenDurable(Topic, MessageListener, String)

listenDurable

public String listenDurable(javax.jms.Topic topic,
                            String messageSelector,
                            javax.jms.MessageListener callback,
                            String subscriptionName)
                     throws MessagingException

This is an asynchronous and durable listen. The caller provides a JMS callback interface reference, and any messages received for the given destination are provided through the onMessage() callback method. If the listener becomes unavailable the JMS provider will store messages received on the given topic until the listener reestablishes a connection and will then deliver those messages. Messages will be filtered based on the provided message selector.

Parameters:

topic - the topic on which to listen

messageSelector - selection criteria for filtering messages

callback - the listener to call when a message is received

subscriptionName - the name of the subscription

Returns:

The subscription name which can be used to stop, unsubscribe, and reconnect to this topic

Throws:

MessagingException

send

public void send(String destName,
                 javax.jms.Message msg)
          throws MessagingException

Allows the caller to send a Message object to a named destination

Throws:

MessagingException

send

public void send(javax.jms.Destination dest,
                 javax.jms.Message msg)
          throws MessagingException

Allows the caller to send a Message object to a destination

Throws:

MessagingException

send

public void send(String destName,
                 Serializable obj)
          throws MessagingException

Allows the caller to send a Serializable object to a destination

Throws:

MessagingException

send

public void send(String destName,
                 String messageText)
          throws MessagingException

Allows the caller to send text to a destination

Throws:

MessagingException

stop

public void stop(String destName)
          throws MessagingException

Stops producers and consumers on a given destination. This has no effect on durable subscriptions.

Parameters:

destName -

Throws:

MessagingException

stopDurable

public void stopDurable(String subscriptionName)
                 throws MessagingException

Stops a durable message consumer. Note that this is not the same as unsubscribing. When a durable message consumer is restarted all messages received since it was stopped will be delivered.

Parameters:

subscriptionName - - the name of the subscription

Throws:

MessagingException

unsubscribeDurable

public void unsubscribeDurable(String subscriptionName)
                        throws MessagingException

Removes the durable subscription with the given name.

Parameters:

subscriptionName - - name of the durable subscription

Throws:

MessagingException

unsubscribeAllDurable

public void unsubscribeAllDurable()
                           throws MessagingException

Removes all durable topic subscriptions created using this JMSManager instance

Throws:

MessagingException

close

public void close()
           throws MessagingException

Throws:

MessagingException

createMapMessage

public javax.jms.MapMessage createMapMessage(String destName)
                                      throws MessagingException

Throws:

MessagingException

createTextMessage

public javax.jms.TextMessage createTextMessage(String destName,
                                               String text)
                                        throws MessagingException

Throws:

MessagingException

createObjectMessage

public javax.jms.ObjectMessage createObjectMessage(String destName,
                                                   Serializable object)
                                            throws MessagingException

Throws:

MessagingException

createBytesMessage

public javax.jms.BytesMessage createBytesMessage(String destName)
                                          throws MessagingException

Throws:

MessagingException

getSession

public javax.jms.Session getSession(String destName)
                             throws MessagingException

Parameters:

destName -

Returns:

the Session object for the specified destination name.

Throws:

Exception

MessagingException

getDestination

public javax.jms.Destination getDestination(String destName)
                                     throws MessagingException

Gets the named Destination if it has been created.

Parameters:

destName -

Returns:

the Destination object for the specified destination name or null if the destination does not exist

Throws:

Exception

MessagingException

getDestinations

public List<javax.jms.Destination> getDestinations()

Provides a listing of the currently available destinations

Returns:

destination list

getProducer

public javax.jms.MessageProducer getProducer(String destName)
                                      throws MessagingException

Parameters:

destName -

Returns:

the MessageProducer object for the specified destination name

Throws:

Exception

MessagingException

getConsumer

public javax.jms.MessageConsumer getConsumer(String destName)
                                      throws MessagingException

Parameters:

destName -

Returns:

the MessageConsumer object for the specified destination name

Throws:

Exception

MessagingException

getDefaultDestinationType

public JMSManager.DestinationType getDefaultDestinationType()

Returns:

the default DestinationType

setDefaultDestinationType

public void setDefaultDestinationType(JMSManager.DestinationType defaultDestinationType)

Sets the default DestinationType

Parameters:

defaultDestinationType -

connectToJMS

protected void connectToJMS(String clientId)
                     throws MessagingException

Throws:

MessagingException

getJMSDestination

protected org.fcrepo.server.messaging.JMSManager.JMSDestination getJMSDestination(String name)
                                                                           throws MessagingException

Throws:

MessagingException

setupProducer

protected void setupProducer(org.fcrepo.server.messaging.JMSManager.JMSDestination jmsDest)
                      throws MessagingException

Throws:

MessagingException

setupAsynchConsumer

protected void setupAsynchConsumer(org.fcrepo.server.messaging.JMSManager.JMSDestination jmsDest,
                                   String messageSelector,
                                   javax.jms.MessageListener callback)
                            throws MessagingException

Throws:

MessagingException

setupSynchConsumer

protected javax.jms.Message setupSynchConsumer(org.fcrepo.server.messaging.JMSManager.JMSDestination jmsDest,
                                               String messageSelector,
                                               int timeout)
                                        throws MessagingException

Throws:

MessagingException

createJMSMessage

protected javax.jms.Message createJMSMessage(Serializable obj,
                                             javax.jms.Session session)
                                      throws javax.jms.JMSException

Throws:

javax.jms.JMSException

getConnection

protected javax.jms.Connection getConnection()
                                      throws MessagingException

Throws:

MessagingException

jndiLookup

protected Object jndiLookup(String name)
                     throws MessagingException

Throws:

MessagingException

getContext

protected Context getContext()
                      throws MessagingException

Throws:

MessagingException