com.infoengine.messaging
Class MsgService

java.lang.Object
  com.infoengine.messaging.MsgService

All Implemented Interfaces:

javax.jms.ExceptionListener

public final class MsgService

extends Object

implements javax.jms.ExceptionListener

General class used to support JMS communications The methods subscribeEvent, unsubscribeEvent and emitEvent along with the com.infoengine.webject.wes.* webjects supply support for the Web Event Service (WES). The WES is I*E's interface to JMS' Publish/Subscribe mechanism. The methods subscribeQueue, unsubscribeQueue, queueTask and queryResults along with the com.infoengine.webject.msg.* webjects supply support for the foundation of messaging queue support and guaranteed task execution.

Nested Class Summary

(package private) class	MsgService.IEJMSRecoveryThread this thread will re-initialize queue and topic support and recover any subscriptions that were lost as a result of the MOM going away
(package private) static interface	MsgService.MOMConnectionPool describes a connection pool
(package private) class	MsgService.MOMHash simple collection of objects similar to a hashtable in that there's only one element per key allowed.
(package private) class	MsgService.MOMHashMember an element in a MOMHash
(package private) class	MsgService.MOMKey object that uniquely identifies an element in a MOMHash
(package private) class	MsgService.MOMSharedConnection a member in a MOMSharedPool
(package private) class	MsgService.MOMSharedPool A simple connection pool used to organize and maintain connections to a MOM.

Field Summary

private ObjectCache	administeredObjectCache
(package private) static String	CLASS
private long	correlationSequence
private String	defaultQueuePass
private String	defaultQueueUser
private String	defaultTopicPass
private String	defaultTopicUser
private MsgService.MOMHash	events
(package private) static String	IE_RESULT_TTL
(package private) static String	PARAM_ATTRIBUTE
(package private) static String	PARAM_BLOBCOUNT
(package private) static String	PARAM_CORR_ID
(package private) static String	PARAM_DELETE
(package private) static String	PARAM_DEST
(package private) static String	PARAM_END_DURABLE_SUBSCRIPTION
(package private) static String	PARAM_EVENT
(package private) static String	PARAM_EXECUTETASK
(package private) static String	PARAM_FAILURETASK
(package private) static String	PARAM_GROUPIN
(package private) static String	PARAM_GROUPOUT
(package private) static String	PARAM_PASS
(package private) static String	PARAM_PRIORITY
(package private) static String	PARAM_PROPERTY
(package private) static String	PARAM_QUEUE
(package private) static String	PARAM_RESULT_TTL
(package private) static String	PARAM_TASK
(package private) static String	PARAM_TASK_TTL
(package private) static String	PARAM_TTLIVE
(package private) static String	PARAM_TYPE
(package private) static String	PARAM_UNIQUE_CORR_ID
(package private) static String	PARAM_USER
(package private) static String	PARAM_WAITTIME
(package private) static String	PARAM_WHERE
private MsgService.MOMConnectionPool	queueConnectionPool
private Context	queueCtx
private javax.jms.QueueConnectionFactory	queueFactory
private MsgService.MOMHash	queues
(package private) static String	queueServiceName
private boolean	queueSupport
private MsgService.IEJMSRecoveryThread	recovery
(package private) static String	RESOURCE
private MsgService.MOMConnectionPool	topicConnectionPool
private javax.jms.TopicConnectionFactory	topicFactory
private boolean	topicSupport
private Context	wesCtx
(package private) static String	wesServiceName

Constructor Summary

private

MsgService() create a new instance of the MsgService pretend we're in a perfect world and let all exceptions fly to be handled by the creator.

Method Summary

Group	browseQueue(Task t) Browse a queue for contents
private IeRequest	buildRequest(Task t, Webject w)
private void	closeEventListener(EventListener listener) close an event listener but don't end its subscription.
private void	closeEventListener(EventListener listener, boolean endDurableSubscription) close an event listener
private void	closeQueueListener(QueueListener listener) close a queue listener
Group	createObject(Task t) <ie:webject name="Create-Object" type="MSG"> <ie:param name="QUEUE" data=""/> (required) <ie:param name="GROUP_OUT" data=""/> <ie:param name="GROUP_IN" data=""/> (multiple) <ie:param name="PROPERTY" data="="/> (multiple) <ie:param name="TIME_TO_LIVE" data=""/> <ie:param name="PRIORITY" data="<0-9>"/> (default 4) <ie:param name="TYPE" data=""/> (default Info*Engine) <ie:param name="PUT_*" data=""/> </ie:webject>
Task	deleteObject(Task t) <ie:webject name="Delete-Object" type="MSG"> <ie:param name="QUEUE" data=""/> (required) <ie:param name="GROUP_OUT" data=""/> <ie:param name="WHERE" data=""/> </ie:webject>
Group	emitEvent(Task t) send a named event
private EventListener	findEventListener(String euri) search for a named event listener
private MsgListener	findListener(String name, String where, MsgService.MOMHash hash) find a MsgListener object in a list
private QueueListener	findQueueListener(String quri, String where) search for a named queue listener
private javax.jms.ConnectionFactory	getConnectionFactory(String serviceName, String property, Context ctx) retrieve a ConnectionFactory object from an LDAP context for serviceName
private EventListener	getEventListener(String euri, String user, String pass, boolean create) lookup an event listener in the events hash.
private EventListener	getEventListener(String euri, String user, String pass, boolean create, boolean subscribe) lookup an event listener in the events hash if create is true and a listener is not found then create a new listener
private Context	getInitialContext(String serviceName) based on ie.properties retrieve an initial context for serviceName
private String	getLocalizedMessage(String key, Object[] inserts) get a localized String from the resource bundle used to put localized status messages
static MsgService	getMsgService(boolean topicSupport, boolean queueSupport) get the MsgService instance
(package private) javax.jms.QueueConnection	getQueueConnection(String user, String pass) retrieve a queue connection from the connection pool sending a user name and password of null will return an anonymous connection.
private QueueListener	getQueueListener(String quri, String user, String pass, String where) lookup an event listener in the events hash if create is true and a listener is not found then create a new listener
private QueueListener	getQueueListener(String quri, String user, String pass, String where, boolean create) lookup an event listener in the events hash if create is true and a listener is not found then create a new listener
private QueueListener	getQueueListener(String quri, String user, String pass, String where, boolean create, boolean createNew) lookup an queue listener in the listener's hash if create is true and a listener is not found then create a new listener
private void	initializeQueueSupport() - initialize LDAP context for Queue related Administered objects - retrieve the QueueConnectionFactory from LDAP - create a QueueConnection to JMS - start the connection - set queue support to true
private void	initializeTopicSupport() - initialize LDAP context for Topic related Administered objects - retrieve the TopicConnectionFactory from LDAP - create a TopicConnection to JMS - start the connection - set topic support to true
private Object	lookupAdminObject(Context ctx, String uri) Lookup an administered object by name
private javax.jms.ConnectionFactory	lookupConnectionFactory(Context ctx, String uri) Lookup ConnectionFactory administered object by name
(package private) javax.jms.Queue	lookupQueue(String uri) Lookup Queue administered object by name
private javax.jms.Topic	lookupTopic(String uri) Lookup Topic administered object by name
private Webject	mapCredentials(Task t, String instance)
private Webject	mapMsgCredentials(Task t)
private Webject	mapWesCredentials(Task t)
private EventListener	newEventListener(javax.jms.Topic topic, String euri, String user, String pass, boolean subscribe) create a new EventListener
private QueueListener	newQueueListener(javax.jms.Queue queue, String quri, String user, String pass, String where) create a new QueueListener
private String	normalizeUri(String uri) prepend 'cn=' to uri if appropriate it's assumed that it's ok for uri to be fully qualified, or relative.
void	onException(javax.jms.JMSException jmse) start a recovery thread when serious connection related problems occur
Task	queryObject(Task t) <ie:webject name="Query-Object" type="MSG"> <ie:param name="QUEUE" data=""/> (required) <ie:param name="WHERE" data=""/> <ie:param name="DELETE" data="true | false"/> (default: true) </ie:webject>
private Task	queryObject(Task t, boolean remove) method supporting query and delete object webjects
Task	queryResults(Task t, boolean remove) Query for the results of a queued task
Group	queueTask(Task t) Queue a named task
(package private) void	releaseQueueConnection(String user, String pass) release a queue connection no longer in use
private void	startRecovery() begin a recovery thread when the MOM goes away
Group	subscribeEvent(Task t) subscribe to listen for a named event
Group	subscribeQueue(Task t) subscribe to a queue for tasks to execute
Group	unsubscribeEvent(Webject w) unsubscribe from a named event
Group	unsubscribeQueue(Task t) unsubscribe from a named queue
private void	updateHash(MsgService.MOMKey key, MsgListener listener, MsgService.MOMHash hash, boolean put) add or remove an item from a Hashtable

Methods inherited from class java.lang.Object

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

Field Detail

administeredObjectCache

private ObjectCache administeredObjectCache

wesServiceName

static final String wesServiceName

See Also:

Constant Field Values

events

private MsgService.MOMHash events

topicFactory

private javax.jms.TopicConnectionFactory topicFactory

wesCtx

private Context wesCtx

topicSupport

private boolean topicSupport

topicConnectionPool

private MsgService.MOMConnectionPool topicConnectionPool

defaultTopicUser

private String defaultTopicUser

defaultTopicPass

private String defaultTopicPass

queueServiceName

static final String queueServiceName

See Also:

Constant Field Values

queues

private MsgService.MOMHash queues

queueFactory

private javax.jms.QueueConnectionFactory queueFactory

queueCtx

private Context queueCtx

queueSupport

private boolean queueSupport

queueConnectionPool

private MsgService.MOMConnectionPool queueConnectionPool

defaultQueueUser

private String defaultQueueUser

defaultQueuePass

private String defaultQueuePass

correlationSequence

private long correlationSequence

RESOURCE

static final String RESOURCE

See Also:

Constant Field Values

CLASS

static final String CLASS

See Also:

Constant Field Values

IE_RESULT_TTL

static final String IE_RESULT_TTL

See Also:

Constant Field Values

PARAM_EVENT

static final String PARAM_EVENT

See Also:

Constant Field Values

PARAM_EXECUTETASK

static final String PARAM_EXECUTETASK

See Also:

Constant Field Values

PARAM_FAILURETASK

static final String PARAM_FAILURETASK

See Also:

Constant Field Values

PARAM_TTLIVE

static final String PARAM_TTLIVE

See Also:

Constant Field Values

PARAM_GROUPIN

static final String PARAM_GROUPIN

See Also:

Constant Field Values

PARAM_GROUPOUT

static final String PARAM_GROUPOUT

See Also:

Constant Field Values

PARAM_PRIORITY

static final String PARAM_PRIORITY

See Also:

Constant Field Values

PARAM_PROPERTY

static final String PARAM_PROPERTY

See Also:

Constant Field Values

PARAM_TYPE

static final String PARAM_TYPE

See Also:

Constant Field Values

PARAM_QUEUE

static final String PARAM_QUEUE

See Also:

Constant Field Values

PARAM_TASK

static final String PARAM_TASK

See Also:

Constant Field Values

PARAM_DEST

static final String PARAM_DEST

See Also:

Constant Field Values

PARAM_WHERE

static final String PARAM_WHERE

See Also:

Constant Field Values

PARAM_WAITTIME

static final String PARAM_WAITTIME

See Also:

Constant Field Values

PARAM_CORR_ID

static final String PARAM_CORR_ID

See Also:

Constant Field Values

PARAM_TASK_TTL

static final String PARAM_TASK_TTL

See Also:

Constant Field Values

PARAM_RESULT_TTL

static final String PARAM_RESULT_TTL

See Also:

Constant Field Values

PARAM_DELETE

static final String PARAM_DELETE

See Also:

Constant Field Values

PARAM_BLOBCOUNT

static final String PARAM_BLOBCOUNT

See Also:

Constant Field Values

PARAM_ATTRIBUTE

static final String PARAM_ATTRIBUTE

See Also:

Constant Field Values

PARAM_USER

static final String PARAM_USER

See Also:

Constant Field Values

PARAM_PASS

static final String PARAM_PASS

See Also:

Constant Field Values

PARAM_UNIQUE_CORR_ID

static final String PARAM_UNIQUE_CORR_ID

See Also:

Constant Field Values

PARAM_END_DURABLE_SUBSCRIPTION

static final String PARAM_END_DURABLE_SUBSCRIPTION

See Also:

Constant Field Values

recovery

private MsgService.IEJMSRecoveryThread recovery

Constructor Detail

MsgService

private MsgService()
            throws Exception

create a new instance of the MsgService pretend we're in a perfect world and let all exceptions fly to be handled by the creator.

Throws:

Exception - this creator does not catch any JNDI, JMS or other Exceptions

Method Detail

getMsgService

public static MsgService getMsgService(boolean topicSupport,
                                       boolean queueSupport)
                                throws Exception

get the MsgService instance

Throws:

Exception - this method does not catch any JNDI, JMS or other Exceptions

initializeTopicSupport

private void initializeTopicSupport()
                             throws Exception

- initialize LDAP context for Topic related Administered objects - retrieve the TopicConnectionFactory from LDAP - create a TopicConnection to JMS - start the connection - set topic support to true

Throws:

Exception - this method does not catch any JNDI, JMS or other Exceptions

initializeQueueSupport

private void initializeQueueSupport()
                             throws Exception

- initialize LDAP context for Queue related Administered objects - retrieve the QueueConnectionFactory from LDAP - create a QueueConnection to JMS - start the connection - set queue support to true

Throws:

Exception - this method does not catch any JNDI, JMS or other Exceptions

getInitialContext

private Context getInitialContext(String serviceName)
                           throws Exception

based on ie.properties retrieve an initial context for serviceName

Returns:

The LDAP Context for serviceName

Throws:

Exception - this method does not catch any JNDI or other Exceptions

getConnectionFactory

private javax.jms.ConnectionFactory getConnectionFactory(String serviceName,
                                                         String property,
                                                         Context ctx)
                                                  throws Exception

retrieve a ConnectionFactory object from an LDAP context for serviceName

Returns:

the ConnectionFactory object retrieved from the directory

Throws:

Exception - no JMS related or other exceptions are caught by this method

Exception

normalizeUri

private String normalizeUri(String uri)

prepend 'cn=' to uri if appropriate
it's assumed that it's ok for uri to be fully qualified, or relative. if uri appears to be relative but doesn't look like a dn, make it relative by placing 'cn=' on the front.

normalize in this case is really a misnomer since uri's coming out won't all be in the same format.

Returns:

the "normalized" uri

updateHash

private void updateHash(MsgService.MOMKey key,
                        MsgListener listener,
                        MsgService.MOMHash hash,
                        boolean put)

add or remove an item from a Hashtable

getLocalizedMessage

private String getLocalizedMessage(String key,
                                   Object[] inserts)

get a localized String from the resource bundle used to put localized status messages

Returns:

localized result

mapCredentials

private Webject mapCredentials(Task t,
                               String instance)

mapWesCredentials

private Webject mapWesCredentials(Task t)

mapMsgCredentials

private Webject mapMsgCredentials(Task t)

emitEvent

public Group emitEvent(Task t)
                throws IEException

send a named event

Throws:

IEException

subscribeEvent

public Group subscribeEvent(Task t)
                     throws IEException

subscribe to listen for a named event

Throws:

IEException

unsubscribeEvent

public Group unsubscribeEvent(Webject w)
                       throws IEException

unsubscribe from a named event

Throws:

IEException

newEventListener

private EventListener newEventListener(javax.jms.Topic topic,
                                       String euri,
                                       String user,
                                       String pass,
                                       boolean subscribe)
                                throws IEException

create a new EventListener

Parameters:

topic - - the topic for the listener

user - - the user name used to connect to the MOM

pass - - the password used to connect to the MOM

subscribe - - whether or not to create a durable subscription to this topic

Throws:

IEException

findListener

private MsgListener findListener(String name,
                                 String where,
                                 MsgService.MOMHash hash)

find a MsgListener object in a list

Parameters:

name - - the name associated with the listener object

where - - the where clause associated with the listener object

hash - - the list to search

findEventListener

private EventListener findEventListener(String euri)
                                 throws IEException

search for a named event listener

Parameters:

euri - - the uri of the event's administered object

Throws:

IEException

findQueueListener

private QueueListener findQueueListener(String quri,
                                        String where)
                                 throws IEException

search for a named queue listener

Parameters:

quri - - the uri of the queue's administered object

where - - the where clause associated with the queue listener

Throws:

IEException

getEventListener

private EventListener getEventListener(String euri,
                                       String user,
                                       String pass,
                                       boolean create)
                                throws IEException

lookup an event listener in the events hash. if create is true and a listener is not found then create a new listener

Returns:

found or new IEEventListener

Throws:

IEException - if error occurs creating new listener

getEventListener

private EventListener getEventListener(String euri,
                                       String user,
                                       String pass,
                                       boolean create,
                                       boolean subscribe)
                                throws IEException

lookup an event listener in the events hash if create is true and a listener is not found then create a new listener

Returns:

found or new IEEventListener

Throws:

IEException - if error occurs creating new listener

closeEventListener

private void closeEventListener(EventListener listener)
                         throws IEException

close an event listener but don't end its subscription.

Throws:

IEException - if error closing listener

closeEventListener

private void closeEventListener(EventListener listener,
                                boolean endDurableSubscription)
                         throws IEException

close an event listener

Throws:

IEException - if error closing listener

closeQueueListener

private void closeQueueListener(QueueListener listener)
                         throws IEException

close a queue listener

Throws:

IEException - if error closing listener

lookupAdminObject

private Object lookupAdminObject(Context ctx,
                                 String uri)
                          throws IEException

Lookup an administered object by name

Throws:

IEException

lookupQueue

javax.jms.Queue lookupQueue(String uri)
                      throws IEException

Lookup Queue administered object by name

Throws:

IEException

lookupTopic

private javax.jms.Topic lookupTopic(String uri)
                             throws IEException

Lookup Topic administered object by name

Throws:

IEException

lookupConnectionFactory

private javax.jms.ConnectionFactory lookupConnectionFactory(Context ctx,
                                                            String uri)
                                                     throws IEException

Lookup ConnectionFactory administered object by name

Throws:

IEException

getQueueListener

private QueueListener getQueueListener(String quri,
                                       String user,
                                       String pass,
                                       String where,
                                       boolean create,
                                       boolean createNew)
                                throws IEException

lookup an queue listener in the listener's hash if create is true and a listener is not found then create a new listener

Returns:

found or new IEEventListener

Throws:

IEException - if error occurs creating new listener

getQueueConnection

javax.jms.QueueConnection getQueueConnection(String user,
                                             String pass)
                                       throws Exception

retrieve a queue connection from the connection pool sending a user name and password of null will return an anonymous connection.

Throws:

Exception - if an error occurs creating the connection

releaseQueueConnection

void releaseQueueConnection(String user,
                            String pass)

release a queue connection no longer in use

newQueueListener

private QueueListener newQueueListener(javax.jms.Queue queue,
                                       String quri,
                                       String user,
                                       String pass,
                                       String where)
                                throws IEException

create a new QueueListener

Parameters:

queue - - the queue to associate the listener with

user - - the user name used to connect to the MOM

pass - - the password used to connect to the MOM

where - - the where clause to associate with the listener

Throws:

IEException

getQueueListener

private QueueListener getQueueListener(String quri,
                                       String user,
                                       String pass,
                                       String where)
                                throws IEException

lookup an event listener in the events hash if create is true and a listener is not found then create a new listener

Returns:

found or new IEEventListener

Throws:

IEException - if error occurs creating new listener

getQueueListener

private QueueListener getQueueListener(String quri,
                                       String user,
                                       String pass,
                                       String where,
                                       boolean create)
                                throws IEException

lookup an event listener in the events hash if create is true and a listener is not found then create a new listener

Returns:

found or new IEEventListener

Throws:

IEException - if error occurs creating new listener

queueTask

public Group queueTask(Task t)
                throws IEException

Queue a named task

Throws:

IEException

queryResults

public Task queryResults(Task t,
                         boolean remove)
                  throws IEException

Query for the results of a queued task

Throws:

IEException

subscribeQueue

public Group subscribeQueue(Task t)
                     throws IEException

subscribe to a queue for tasks to execute

Throws:

IEException

browseQueue

public Group browseQueue(Task t)
                  throws IEException

Browse a queue for contents

Throws:

IEException

unsubscribeQueue

public Group unsubscribeQueue(Task t)
                       throws IEException

unsubscribe from a named queue

Throws:

IEException

buildRequest

private IeRequest buildRequest(Task t,
                               Webject w)

createObject

public Group createObject(Task t)
                   throws IEException

<ie:webject name="Create-Object" type="MSG"> <ie:param name="QUEUE" data=""/> (required) <ie:param name="GROUP_OUT" data=""/> <ie:param name="GROUP_IN" data=""/> (multiple) <ie:param name="PROPERTY" data="="/> (multiple) <ie:param name="TIME_TO_LIVE" data=""/> <ie:param name="PRIORITY" data="<0-9>"/> (default 4) <ie:param name="TYPE" data=""/> (default Info*Engine) <ie:param name="PUT_*" data=""/> </ie:webject>

Throws:

IEException

deleteObject

public Task deleteObject(Task t)
                  throws IEException

<ie:webject name="Delete-Object" type="MSG"> <ie:param name="QUEUE" data=""/> (required) <ie:param name="GROUP_OUT" data=""/> <ie:param name="WHERE" data=""/> </ie:webject>

Throws:

IEException

queryObject

public Task queryObject(Task t)
                 throws IEException

<ie:webject name="Query-Object" type="MSG"> <ie:param name="QUEUE" data=""/> (required) <ie:param name="WHERE" data=""/> <ie:param name="DELETE" data="true | false"/> (default: true) </ie:webject>

Throws:

IEException

queryObject

private Task queryObject(Task t,
                         boolean remove)
                  throws IEException

method supporting query and delete object webjects

Throws:

IEException

startRecovery

private void startRecovery()

begin a recovery thread when the MOM goes away

onException

public void onException(javax.jms.JMSException jmse)

start a recovery thread when serious connection related problems occur

Specified by:

onException in interface javax.jms.ExceptionListener