io.mats3.impl.jms

Interface JmsMatsJmsSessionHandler

All Known Implementing Classes:

JmsMatsJmsSessionHandler_Pooling, JmsMatsJmsSessionHandler_Simple

public interface JmsMatsJmsSessionHandler

Interface for implementing JMS Connection and JMS Session handling. This can implement both different connection sharing mechanisms, and should implement some kind of Session pooling for initiators. It can also implement logic for "is this connection up?" mechanisms, to minimize the gap whereby a JMS Connection is in a bad state but the application has not noticed this yet.

The reason for session pooling for initiators is that a JMS Session can only be used for one thread, and since initiators are shared throughout the code base, one initiator might be used by several threads at the same time.

For reference wrt. cardinality between Sessions and Connections: In the JCA spec, it is specified that one JMS Connection is used per one JMS Session (and in the JMS spec v2.0, this is "formalized" in that in the "simplified JMS API" one have a new class JMSContext, which combines a Connection and Session in one). This will here mean that for each JmsMatsTransactionManager.JmsMatsTxContextKey, there shall be a unique JMS Connection (i.e. each StageProcessor has its own Connection). It does makes some sense, though, that JMS Connections at least are shared for all StageProcessors for a Stage - or even for all StageProcessors for all Stages of an Endpoint. Otherwise, a large system built on Mats will use a pretty massive amount of Connections. However, sharing one Connection for the entire application/service (i.e. for all endpoints in the JVM) might be a bit too heavy burden for a single JMS Connection.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	JmsMatsJmsSessionHandler.JmsSessionHolder A "sidecar object" for the JMS Session, so that additional stuff can be bound to it.

Method Summary

Modifier and Type	Method and Description
int	closeAllAvailableSessions() Closes all Available Session, does not touch Employed.
JmsMatsJmsSessionHandler.JmsSessionHolder	getSessionHolder(io.mats3.impl.jms.JmsMatsInitiator<?> initiator) Will be invoked every time an Initiator wants to send a message - it will be returned after the message(s) is sent.
JmsMatsJmsSessionHandler.JmsSessionHolder	getSessionHolder(io.mats3.impl.jms.JmsMatsStageProcessor<?,?,?,?> processor) Will be invoked before the StageProcessor goes into its consumer loop - it will be closed once the Stage is stopped, or if the Session "crashes", i.e.

Method Detail

getSessionHolder

JmsMatsJmsSessionHandler.JmsSessionHolder getSessionHolder(io.mats3.impl.jms.JmsMatsInitiator<?> initiator)
                                                    throws JmsMatsException.JmsMatsJmsException

Will be invoked every time an Initiator wants to send a message - it will be returned after the message(s) is sent.

Parameters:

initiator - the initiator in question.

Returns:

a JmsMatsJmsSessionHandler.JmsSessionHolder instance - which is not the same as any other SessionHolders concurrently in use (but it may be pooled, so after a JmsMatsJmsSessionHandler.JmsSessionHolder.release(), it may be returned to another invocation again).

Throws:

JmsMatsException.JmsMatsJmsException - if there was a problem getting a Connection. Problems getting a Sessions (e.g. the current Connection is broken) should be internally handled (i.e. try to get a new Connection), except if it can be determined that the problem getting a Session is of a fundamental nature (i.e. the credentials can get a Connection, but cannot get a Session - which would be pretty absurd, but hey).

getSessionHolder

JmsMatsJmsSessionHandler.JmsSessionHolder getSessionHolder(io.mats3.impl.jms.JmsMatsStageProcessor<?,?,?,?> processor)
                                                    throws JmsMatsException.JmsMatsJmsException

Will be invoked before the StageProcessor goes into its consumer loop - it will be closed once the Stage is stopped, or if the Session "crashes", i.e. a method on Session or some downstream API throws an Exception.

Parameters:

processor - the StageProcessor in question.

Returns:

a JmsMatsJmsSessionHandler.JmsSessionHolder instance - which is unique for each call.

Throws:

JmsMatsException.JmsMatsJmsException - if there was a problem getting a Connection. Problems getting a Sessions (e.g. the current Connection is broken) should be internally handled (i.e. try to get a new Connection), except if it can be determined that the problem getting a Session is of a fundamental nature (i.e. the credentials can get a Connection, but cannot get a Session - which would be pretty absurd, but hey).

closeAllAvailableSessions

int closeAllAvailableSessions()

Closes all Available Session, does not touch Employed. Net result is that it Connections that do not have any employed Sessions will be closed. The use case for this is to "clear out" the JmsMatsJmsSessionHandler upon shutdown - the returned value is a count of how many Connections are still alive after the operation, which should be 0.

Returns:

the number of Connections still alive after the operation (in the assumed use case, this should be zero).