com.solacesystems.jcsmp.transaction

Interface TransactedSession

public interface TransactedSession

A TransactedSession groups a number of guaranteed delivery flows together to allow them to perform transactions. Once successfully acquired, a TransactedSession has an in-progress transaction and zero associated flows.

A TransactedSession always has exactly one active transaction. Calling commit() commits the in-progress transaction and performs the session's input and output operations (messages received or sent during the transaction). A new transaction is automatically started.

Associating Guaranteed-Delivery Flows

Once a TransactedSession has been acquired, associate publisher or consumer flows to it by calling createProducer(...) and createFlow(...). Guaranteed messages sent or consumed on these flows contribute to the active transaction's steps. NOTE: TransactedSession publishers require an existing producer in the underlying JCSMPSession. Applications that wish to create a XMLMessageProducer must first call JCSMPSession#GetMessageProducer().

Threading Model

This interface is not safe for use by multiple application threads, with the exception of close(), which may be called by any thread.

Similarly to JMS transacted sessions, all the producer / consumer flows which are part of a TransactedSession must be accessed serially by the same thread.

• For example, if using synchronous message consumers, any send operation and receive operation must be done by the same thread, and this thread must be the one calling commit().
  

   SYNCH CONSUMERS: The application thread serializes access to
                    Producers / Consumers of a session.
                    
   +------------------+                       +---+
   |APPLICATION THREAD|                       |API|
   +---------+--------+                       +-+-+
             |                                  |
             | XMLMessageProducer.send()        |
             +--------------------------------->|
             |                                  |
             | XMLMessageProducer.send()        |
             +--------------------------------->|
             |                                  |
             | FlowReceiver.receive()           |
             +--------------------------------->|
             |              XMLMessage          |
             |  <-------------------------------+
             |                                  |
             |                                  |
             |                                  |
             | TransactedSession.commit()       |
             +--------------------------------->|
             |                                  |
             |                                  |
             |                                  | 
   

• If using asynchronous message consumers, an API-owned thread delivers messages to registered message listeners. This thread must be the one to send messages and call commit() or rollback().
  

   ASYNCH CONSUMERS: The API thread serializes access to
                     Producers / Consumers of a session.
  
   +----------------+      +-----------+                 +---+
   |API NOTIF THREAD|      |APPLICATION|                 |API|
   +---------+------+      +-+---------+                 +-+-+
             |               |                             |
             | onReceive()   |                             |
             +-------------->|                             |
             |               | XMLMessageProducer.send()   |
             |               +---------------------------->|
             |               |                             |
             |               | XMLMessageProducer.send()   |
             |               +---------------------------->|
             |               |                             |
             |               | TransactedSession.commit()  |
             |               +---------------------------->|
             |   return      |                             |
             | <-------------+                             |
             |               |                             |
             |               |                             |
             |               |                             |
             |               |                             |
   

Since:

5.3

Method Summary

Modifier and Type	Method and Description
void	close() Rollback the active transaction and close the TransactedSession.
void	commit() Commit the active transaction.
FlowReceiver	createFlow(XMLMessageListener listener, ConsumerFlowProperties flowProps, EndpointProperties endpointProps) Creates a consumer flow within this TransactedSession and associates it to this session.
FlowReceiver	createFlow(XMLMessageListener listener, ConsumerFlowProperties flowProps, EndpointProperties endpointProps, FlowEventHandler flowEventHandler) Creates a consumer flow within this TransactedSession and associates it to this session.
XMLMessageProducer	createProducer(ProducerFlowProperties fprop, JCSMPStreamingPublishEventHandler callback) Creates a producer flow within this TransactedSession and associates it to this session.
XMLMessageProducer	createProducer(ProducerFlowProperties fprop, JCSMPStreamingPublishEventHandler streamCallback, JCSMPProducerEventHandler eventCallback) Creates a producer flow within this TransactedSession and associates it to this session.
String	getName() Gets the name of this session.
TransactionStatus	getStatus() Gets the status of the current transaction.
void	rollback() Rollback the active transaction.

Method Detail

getStatus

TransactionStatus getStatus()

Gets the status of the current transaction.

Returns:

An enum representing the status of the current transaction on this session.

getName

String getName()

Gets the name of this session.

This call is useful for debugging purposes, the name of a transacted session can be used to find the appropriate session in the router CLI.

Returns:

This session's name.

commit

void commit()
     throws RollbackException,
            TransactionResultUnknownException,
            JCSMPException

Commit the active transaction. Blocks until successfully committed or a rollback occurs.

Throws:

RollbackException - If the transaction was rolled back unexpectedly.

TransactionResultUnknownException - If the transaction result is unknown. This could happen when the transacted session could not be resumed after a session reconnection.

JCSMPException - On other exceptions.

rollback

void rollback()
       throws JCSMPException

Rollback the active transaction. Blocks until successfully rolled back or an error occurs.

Throws:

JCSMPException - On exception.

createFlow

FlowReceiver createFlow(XMLMessageListener listener,
                        ConsumerFlowProperties flowProps,
                        EndpointProperties endpointProps)
                 throws JCSMPException

Creates a consumer flow within this TransactedSession and associates it to this session.

The semantics and error conditions of this call are identical to JCSMPSession.createFlow(XMLMessageListener, ConsumerFlowProperties, EndpointProperties).

Throws:

JCSMPException

createFlow

FlowReceiver createFlow(XMLMessageListener listener,
                        ConsumerFlowProperties flowProps,
                        EndpointProperties endpointProps,
                        FlowEventHandler flowEventHandler)
                 throws JCSMPException

Creates a consumer flow within this TransactedSession and associates it to this session.

The semantics and error conditions of this call are identical to JCSMPSession.createFlow(XMLMessageListener, ConsumerFlowProperties, EndpointProperties, FlowEventHandler).

Throws:

JCSMPException

createProducer

XMLMessageProducer createProducer(ProducerFlowProperties fprop,
                                  JCSMPStreamingPublishEventHandler callback)
                           throws JCSMPException

Creates a producer flow within this TransactedSession and associates it to this session. A maximum of one (1) producer flow may be created per TransactedSession. Only streaming producers are allowed, so callback must not be null. NOTE: TransactedSession publishers require an existing producer in the underlying JCSMPSession. Applications that wish to create a XMLMessageProducer must first call JCSMPSession#GetMessageProducer().

Parameters:

fprop - The producer flow properties. If null, the default window size of 255 will be used.

callback - he event handler which has to implement the at least the interface JCSMPStreamingPublishEventHandler.

Returns:

a new producer with its own producer flow

Throws:

InvalidOperationException - If the peer capabilities do not support features requested in this operation.

JCSMPException - On other errors.

createProducer

XMLMessageProducer createProducer(ProducerFlowProperties fprop,
                                  JCSMPStreamingPublishEventHandler streamCallback,
                                  JCSMPProducerEventHandler eventCallback)
                           throws JCSMPException

Creates a producer flow within this TransactedSession and associates it to this session. A maximum of one (1) producer flow may be created per TransactedSession. Only streaming producers are allowed, so callback must not be null. NOTE: TransactedSession publishers require an existing producer in the underlying JCSMPSession. Applications that wish to create a XMLMessageProducer must first call JCSMPSession#GetMessageProducer().

Parameters:

fprop - The producer flow properties. If null, the default window size of 255 will be used.

streamCallback - A stream event handler

eventCallback - A producer event handler

Returns:

a new producer with its own producer flow

Throws:

InvalidOperationException - If the peer capabilities do not support features requested in this operation.

JCSMPException - On other errors.

Since:

7.1.2

close

void close()

Rollback the active transaction and close the TransactedSession. This call closes all subordinate guaranteed delivery flows (producers / consumers).