com.solacesystems.solclientj.core.handle

Interface TransactedSessionHandle

All Superinterfaces:

Handle

public interface TransactedSessionHandle
extends Handle

The TransactedSessionHandle interface represents a messaging API -transacted-session which provides interfaces for local transacations with the Appliance. Applications that need this interface must instantiate an object with the TransactedSessionHandle interface by calling Allocator.newTransactedSessionHandle()

Before the TransactedSessionHandle can be used, a native transacted session must be created on a native non-transacted session with SessionHandle.createTransactedSessionForHandle().

Client applications can create one or more transacted sessions within a non-transacted session. The lifecycle of a transacted session is bounded by the lifecycle of its non-transacted parent session. In other words, when a session is destroyed/disposed, all transacted sessions created within this session will be destroyed/disposed too. A transacted session can have at most one publisher flow and zero or many subscriber flows. All messages sent/received by a transacted session must have a guaranteed delivery mode, there is no support for direct transport messages.

Message Dispatcher:

Asynchronous message delivery to client applications within a Transacted Session (i.e. message consumers created from Transacted Sessions) cannot happen over the context thread. Therefore, asynchronous message delivery within a Transacted Session will be done within an implicitly created Message Dispatcher.

There are two types of Message Dispatchers, which client applications can choose when a Transacted Session is created.

• Context-bound: A Message Dispatcher lazily created by the Context. A Context can have at most one context-bound Message Dispatcher.
• TransactedSession-bound: A Message Dispatcher lazily created by a Transacted Session.

The lifecycle of a message dispatcher is bounded to the lifecycle of the corresponding API object. There are advantages and disadvantages when usingTransactedSession-bound message dispatchers.

• The main advantage is improved responsiveness. It is also possible to improve application performance, especially with multi-core processors.
• The main disadvantage is that programming and debugging is more complex as applications must be more multi-thread aware. In environments where there is contention for CPU resources, there is more overhead managing and switching between threads.

Receiving Messages:

The main differences between receiving messages from a transacted consumer Flow and from a non-transacted Flow are:

• For a transacted consumer Flows (created by TransactedSessionHandle.createFlowForHandle(com.solacesystems.solclientj.core.handle.FlowHandle, java.lang.String[], com.solacesystems.solclientj.core.resource.Endpoint, com.solacesystems.solclientj.core.resource.Subscription, com.solacesystems.solclientj.core.event.MessageCallback, com.solacesystems.solclientj.core.event.FlowEventCallback)), the method FlowHandle.ack(long) returns SolEnum.ReturnCode.OK and no operation (NOP) is performed.
• If a message callback is provided when a transacted consumer Flow is created, messages received on the flow are dispatched to the callbacks just as on non-transacted Flows, but in the context of an internal Contex-bound or TransactedSession-bound Message Dispatcher thread.
• For transacted Flows created without a message callback, messages received on Flows are queued internally. Applications must call function FlowHandle.receive(com.solacesystems.solclientj.core.handle.MessageHandle, int) directly to retrieve messages from those internal queues.

Publishing Messages:

To publish guaranteed messages on a Transacted Session, Transacted Session property TransactedSessionHandle.PROPERTIES.HAS_PUBLISHER must be enabled when the Transacted Session is created.

The main differences between publishing guaranteed messages from a Transacted Session and from a Session are:

• For a Transacted Session, window size is set with TransactedSessionHandle.PROPERTIES.PUB_WINDOW_SIZE. When connecting to PubSub+ brokers 9.8.1 or later, this property allows the application to reduce the outstanding window if there are memory/resource restrictions that preclude the larger window. For example, if the application is only publishing large or max size messages (30mb), it may wish to restrict the number in flight.
• For a Transacted Session, a successful commit acknowledges published messages.

Multithreading:

Transacted Sessions are not thread-safe and a single Transacted Session should not be accessed by multiple application threads. The legal use cases for a transacted session, which are not enforced by the API, are limited to:

• If messages are received by a message callback, invoke commit/rollback/sendMsg only from the message callback (i.e. in the context of an internal Message Dispatcher thread).
• If messages are received from an application thread by calling FlowHandle.receive(com.solacesystems.solclientj.core.handle.MessageHandle, int) directly, TransactedSessionHandle.commit()/TransactedSessionHandle.rollback()/TransactedSessionHandle.send(com.solacesystems.solclientj.core.handle.MessageHandle)/FlowHandle.receive(com.solacesystems.solclientj.core.handle.MessageHandle, int) functions must be called in the context of the same application thread.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TransactedSessionHandle.PROPERTIES Defines the property names used to create a transacted session handle

Method Summary

Modifier and Type	Method and Description
int	commit() Commit the active transaction of a specified Transacted Session.
int	createFlowForHandle(FlowHandle in_out_flowHandle, java.lang.String[] flowProperties, Endpoint endpoint, Subscription subscription, MessageCallback messageCallback, FlowEventCallback flowEventCallback) Create a transacted consumer Flow within a specified Transacted Session.
SessionHandle	getSession() Returns the associated SessionHandle
java.lang.String	getSessionName()
int	rollback() Rollback the active transaction of a specified Transacted Session.
int	send(MessageHandle msg) Sends a Guaranteed Delivery message on the specified Transacted Session.

Methods inherited from interface com.solacesystems.solclientj.core.handle.Handle

destroy, isBound

Method Detail

commit

int commit()
    throws SolclientException

Commit the active transaction of a specified Transacted Session.

Returns:

SolEnum.ReturnCode.OK on success.

SolEnum.ReturnCode.ROLLBACK if a rollback is received and the Transacted Session is still active.

SolEnum.ReturnCode.NOT_READY if the underlying transport is not connected

Throws:

SolclientException - When commit() throws an exception, the status of the outstanding commit request cannot be determined. The commit may have succeeded on the message-router before the response was lost. Or the commit request may have failed (roll back). Applications that treat the failure as a rollback must allow for duplicate transactions.

rollback

int rollback()
      throws SolclientException

Rollback the active transaction of a specified Transacted Session.

Returns:

SolEnum.ReturnCode.OK on success.

SolEnum.ReturnCode.NOT_READY if the underlying transport is not connected

Throws:

SolclientException

createFlowForHandle

int createFlowForHandle(FlowHandle in_out_flowHandle,
                        java.lang.String[] flowProperties,
                        Endpoint endpoint,
                        Subscription subscription,
                        MessageCallback messageCallback,
                        FlowEventCallback flowEventCallback)
                 throws SolclientException

Create a transacted consumer Flow within a specified Transacted Session. If a MessageCallback is provided, messages received on the flow are dispatched to the callback in a context of a Message Dispatcher thread. If there is no MessageCallback (i.e. messageCallback parameter is NULL), messages received on the Flow are queued internally. Applications must call FlowHandle.receive(com.solacesystems.solclientj.core.handle.MessageHandle, int) directly to retrieve the queued messages.

Unlike non-transacted Flows, events and messages received on a transacted Flow are delivered in the context of two different threads. Events are still delivered in a context of the context thread, but messages are dispatched to the Flow MessageCallback in the context of a Message Dispatcher thread or are retrieved by calling FlowHandle.receive(com.solacesystems.solclientj.core.handle.MessageHandle, int) from the context of an application thread. The following flow properties are not supported by transacted Flows:

• FlowHandle.PROPERTIES.ACKMODE
• FlowHandle.PROPERTIES.BROWSER
• FlowHandle.PROPERTIES.MAX_UNACKED_MESSAGES

Parameters:

in_out_flowHandle -

flowProperties - FlowHandle.PROPERTIES

endpoint - Description of the endpoint on the appliance.

subscription - Optional subscription to add if the endpoint is a topic endpoint.

messageCallback - Optional MessageCallback for incoming messages.

flowEventCallback - FlowEventCallback

Returns:

SolEnum.ReturnCode

Throws:

SolclientException

getSessionName

java.lang.String getSessionName()
                         throws SolclientException

Returns:

the transacted session name. Note: The returned String is allocated from the heap and could cause garbage collection interruptions when it is no longer referenced. Applications sensitive to garbage collection should avoid using this method.

Throws:

SolclientException

getSession

SessionHandle getSession()
                  throws SolclientException

Returns the associated SessionHandle

Returns:

the associated SessionHandle

Throws:

SolclientException

send

int send(MessageHandle msg)
  throws SolclientException

Sends a Guaranteed Delivery message on the specified Transacted Session. The message is composed of a number of optional components that are specified by the MessageHandle. The application should first allocate a MessageHandle, then use the methods defined on that object to build the message to send. A successful TransactedSessionHandle.commit() acknowledges published messages delivered to the Solace messaging appliance.

Parameters:

msg - MessageHandle

Returns:

SolEnum.ReturnCode.OK

SolEnum.ReturnCode.NOT_READY if the underlying transport is not connected

Throws:

SolclientException