com.solacesystems.solclientj.core.handle

Interface FlowHandle

All Superinterfaces:

Handle, MessageDispatcher, MessageSupport, StatsSupport

public interface FlowHandle
extends Handle, MessageDispatcher, MessageSupport, StatsSupport

The FlowHandle interface allows applications to receive messages and events on a flow. Applications that need this interface must instantiate an object with the FlowHandle interface by calling Allocator.newFlowHandle() Before the FlowHandle interface can be used, it must be associated with a native flow object by the SessionHandle method SessionHandle.createFlowForHandle().

A flow is an API concept that allows the application to receive messages from an Endpoint on the Appliance (see Endpoint).

Flows are not used by clients that receive Direct messages. Rather, SolEnum.MessageDeliveryMode.DIRECT messages are received by clients with matching subscriptions directly from the Appliance's message bus through sessions (see SessionHandle) instead of binding to a specific Endpoint on the message bus.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	FlowHandle.PROPERTIES Defines the property names used to configure a Flow handle

Method Summary

Modifier and Type	Method and Description
int	ack(long adMsgId) Sends an acknowledgement for a message received over this flow.
int	ack(MessageHandle messageHandle) Sends an acknowledgement for a message received over this flow.
Destination	getDestination() Returns the Destination to which messages should be published to get to this flow's bound Endpoint.
FlowEvent	getFlowEvent() This method returns a FlowEvent instance in the context of FlowEventCallback.onEvent().
java.lang.String	getProperty(java.lang.String flowPropertyName) Gets the value of the specified Flow property for the Flow.
SessionHandle	getSession() Returns the SessionHandle associated with this flow
TransactedSessionHandle	getTransactedSession() Returns the TransactedSessionHandle.
int	receive(MessageHandle in_out_MsgHandle, int timeout) Note: This operation is only supported on a Transacted Flow, which must have been created on a TransactedSessionHandle
int	setMaxUnacked(int numOfMaxUnackedMsgs) Changes the maximum number of unacknowledged messages that may be received on the specified Flow.
int	settle(long adMsgId, int messageOutcome) Settles a message in a requested way.
int	settle(MessageHandle messageHandle, int messageOutcome) Settles a message in a requested way.
int	start() Opens the receiver on the specified Flow.
int	stop() Closes the receiver on the specified Flow.
void	takeFlowEvent(FlowEvent flowEvent, boolean withInfoString) This method clones the last FlowEvent into the given FlowEvent The given FlowEvent is implementation specific and is expected to be the one produced by Allocator.newFlowEvent() This call is valid while on the same thread and in context of FlowEventCallback.onEvent().

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

destroy, isBound

Methods inherited from interface com.solacesystems.solclientj.core.event.MessageDispatcher

subscribe, subscribe, unsubscribe, unsubscribe

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

getRxMessage, takeRxMessage

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

clearStats, getRxStats, getTxStats

Method Detail

getFlowEvent

FlowEvent getFlowEvent()

This method returns a FlowEvent instance in the context of FlowEventCallback.onEvent().

• This FlowEvent instance is mutable, it always represents the latest flow event data as it is reused when new flow events occur.
• Client applications should call { FlowHandle.takeFlowEvent() to get a cloned copy of the last FlowEvent

.

Returns:

FlowEvent

takeFlowEvent

void takeFlowEvent(FlowEvent flowEvent,
                   boolean withInfoString)

This method clones the last FlowEvent into the given FlowEvent

• The given FlowEvent is implementation specific and is expected to be the one produced by Allocator.newFlowEvent()
• This call is valid while on the same thread and in context of FlowEventCallback.onEvent().

Parameters:

flowEvent - a FlowEvent produced by Allocator.newFlowEvent()

withInfoString - Controls if the info String of the event should be obtained. This will cause object allocation and consequently garbage collection, this should only be set to true for diagnosis.

ack

int ack(long adMsgId)
 throws SolclientException

Sends an acknowledgement for a message received over this flow.

This instructs the API to consider the specified asMsgId acknowledged at the application layer. The library does not send acknowledgements immediately. It stores the state for acknowledged messages internally and acknowledges messages, in bulk, when a threshold or timer is reached.

Applications must only acknowledge a message on the Flow on which it is received. Using the adMsgId received on one Flow when acknowledging on another may result in no message being removed from the message-spool or the wrong message being removed from the message-spool.

NOTE: Ack is equivalent to invoking FlowHandle.settle with a message outcome of SolEnum.MessageOutcome#ACCEPTED The exact behavior of ack() is controlled by Flow property FlowHandle.PROPERTIES.ACKMODE

• SolEnum.AckMode.AUTO - messages are acknowledged automatically by C API and calling this function has no effect.
• SolEnum.AckMode.CLIENT- every message received must be acknowledged by the application through individual calls to ack().

WARNING: If FlowHandle.PROPERTIES.ACKMODE is set to SolEnum.AckMode.AUTO (the default behavior), the function returns SolEnum.ReturnCode.OK, but with a warning that ack() is ignored as the flow is in auto-ack mode.

Parameters:

adMsgId - retrieved from MessageHandle.getGuaranteedMessageId()

Returns:

SolEnum.ReturnCode.OK if successful

Throws:

SolclientException - if the operation fails

settle

int settle(long adMsgId,
           int messageOutcome)
    throws SolclientException

Settles a message in a requested way.

Invoking this method with on a FlowHandle configured to use SolEnum.AckMode.AUTO (the default behaviour) will have no effect and a warning log is issued.

Parameters:

adMsgId - retrieved from MessageHandle.getGuaranteedMessageId()

messageOutcome - type of the message settlement outcome, not expected to be null It can be one of the following:

• SolEnum.MessageOutcome.ACCEPTED
• SolEnum.MessageOutcome.FAILED
• SolEnum.MessageOutcome.REJECTED

Returns:

SolEnum.ReturnCode.OK if successful

Throws:

SolclientException - can be thrown and queried for SolEnum.SubCode:

• SolEnum.SubCode.AD_APP_ACK_FAILED_NOT_SUPPORTED broker does not support specified negative MessageOutcome option
• SolEnum.SubCode#INVALID_FLOW_OPERATION when attempting to use negative MessageOutcome on a FlowHandle that is not configured with FlowHandle.PROPERTIES.REQUIRED_OUTCOME_FAILED or FlowHandle.PROPERTIES.REQUIRED_OUTCOME_REJECTED

See Also:

SolEnum.MessageOutcome for detailed explanation of available options

ack

int ack(MessageHandle messageHandle)
 throws SolclientException

Sends an acknowledgement for a message received over this flow.

This instructs the API to consider the message contained in the specified MessageHandle acknowledged at the application layer. The library does not send acknowledgements immediately. It stores the state for acknowledged messages internally and acknowledges messages, in bulk, when a threshold or timer is reached.

Applications must only acknowledge a message on the Flow on which it is received. Using the messageHandle received on one Flow when acknowledging on another may result in no message being removed from the message-spool or the wrong message being removed from the message-spool. The exact behavior of ack() is controlled by Flow property FlowHandle.PROPERTIES.ACKMODE

• SolEnum.AckMode.AUTO - messages are acknowledged automatically by C API and calling this function has no effect.
• SolEnum.AckMode.CLIENT- every message received must be acknowledged by the application through individual calls to ack().

WARNING: If FlowHandle.PROPERTIES.ACKMODE is set to SolEnum.AckMode.AUTO (the default behavior), the function returns SolEnum.ReturnCode.OK, but with a warning that ack() is ignored as the flow is in auto-ack mode.

Parameters:

messageHandle - received persistent message.

Returns:

SolEnum.ReturnCode.OK if successful

Throws:

SolclientException - if the operation fails

settle

int settle(MessageHandle messageHandle,
           int messageOutcome)
    throws SolclientException

Settles a message in a requested way.

Invoking this method with on a FlowHandle configured to use SolEnum.AckMode.AUTO (the default behaviour) will have no effect and a warning log is issued.

Parameters:

messageHandle - received persistent message.

messageOutcome - type of the message settlement outcome, not expected to be null It can be one of the following:

• SolEnum.MessageOutcome.ACCEPTED
• SolEnum.MessageOutcome.FAILED
• SolEnum.MessageOutcome.REJECTED

Returns:

SolEnum.ReturnCode.OK if successful

Throws:

SolclientException - can be thrown and queried for SolEnum.SubCode:

• SolEnum.SubCode.AD_APP_ACK_FAILED_NOT_SUPPORTED broker does not support specified negative MessageOutcome option
• SolEnum.SubCode#INVALID_FLOW_OPERATION when attempting to use negative MessageOutcome on a FlowHandle that is not configured with FlowHandle.PROPERTIES.REQUIRED_OUTCOME_FAILED or FlowHandle.PROPERTIES.REQUIRED_OUTCOME_REJECTED

See Also:

SolEnum.MessageOutcome for detailed explanation of available options

getDestination

Destination getDestination()
                    throws SolclientException

Returns the Destination to which messages should be published to get to this flow's bound Endpoint.

If bound to a TopicEndpoint, the returned Destination will be of type Topic

If bound to a Queue, the returned Destination will be of type Queue

Otherwise, a null is returned

The Destination returned can be used to set the ReplyTo field in a message, or otherwise communicated to partners that need to send messages to this Flow. This is especially useful for non durable endpoints (Queues and Topic Endpoints), as the destination is unknown before the endpoint is created.

Returns:

a Destination instance

Throws:

SolclientException - if the operation fails

receive

int receive(MessageHandle in_out_MsgHandle,
            int timeout)
     throws SolclientException

Note: This operation is only supported on a Transacted Flow, which must have been created on a TransactedSessionHandle

This method waits until timeout or a message received, no wait if timeout=0.

Parameters:

in_out_MsgHandle - - an unbound MessageHandle that will contain the received message on success.

timeout - - timeout in milliseconds, 0 means no wait.

Returns:

SolEnum.ReturnCode

• SolEnum.ReturnCode.OK with a bound MessageHandle if queue is not empty,
• SolEnum.ReturnCode.OK with and unbound MessageHandle when timeout or queue is empty and timeout=0.
• SolEnum.ReturnCode.NOT_READY with subcode SolEnum.SubCode.SESSION_NOT_ESTABLISHED or SolEnum.SubCode.NO_TRANSACTION_STARTED.

Throws:

SolclientException - if the operation fails The exception can be queried for SolEnum.SubCode:

• SolEnum.SubCode.INVALID_FLOW_OPERATION if the flow is not a Transacted Flow
• SolEnum.SubCode.FLOW_UNBOUND if the flow is unbound and there are no buffered messages within the API waiting for delivery.

getTransactedSession

TransactedSessionHandle getTransactedSession()
                                      throws SolclientException

Returns the TransactedSessionHandle.

When Flows are created within a Transacted Session (see TransactedSessionHandle.createFlowForHandle()), this routine can be used if the application has a FlowHandle and needs to determine the associated Transacted Session. For example, in FlowEventCallback.onEvent() in which a FlowHandle is provided, an application can use this routine to determine the associated Transacted Session.

Returns:

TransactedSessionHandle

Throws:

SolclientException

See Also:

TransactedSessionHandle

getSession

SessionHandle getSession()
                  throws SolclientException

Returns the SessionHandle associated with this flow

When flows are created within a Session (see SessionHandle.createFlowForHandle()), then this routine can be used if the application has a FlowHandle and needs to determine the associated Session. For example, in FlowEventCallback.onEvent() in which a FlowHandle is provided, an application can use this routine to determine the associated Session.

Returns:

SessionHandle

Throws:

SolclientException

See Also:

SessionHandle

stop

int stop()
  throws SolclientException

Closes the receiver on the specified Flow. This method will close the Flow window to the appliance so further messages will not be received until FlowHandle.start() is called. Messages in transit when this method is called will still be delivered to the application. So the application must expect that the MessageCallback.onMessage() receive message callback can be called even after calling stop(). The maximum number of messages that may be in transit at any one time is controlled by FlowHandle.PROPERTIES.WINDOWSIZE and FlowHandle.PROPERTIES.MAX_UNACKED_MESSAGES (see FlowHandle.setMaxUnacked(int)).

A Flow can be created with the window closed by setting the Flow property FlowHandle.PROPERTIES.START_STATE to SolEnum.BooleanValue#DISABLE. When a Flow is created in this way, messages will not be received on the Flow until after FlowHandle.start() is called.

Returns:

SolEnum.ReturnCode

Throws:

SolclientException - if the operation fails

start

int start()
   throws SolclientException

Opens the receiver on the specified Flow. This method opens the Flow window to the appliance so further messages can be received. For browser flows (FlowHandle.PROPERTIES.BROWSER), applications have to call the function to get more messages. A Flow may be created with the window closed by setting the Flow property FlowHandle.PROPERTIES.START_STATE to SolEnum.BooleanValue#DISABLE. When a Flow is created in this way, messages will not be received on the Flow until after start() is called.

Returns:

SolEnum.ReturnCode

Throws:

SolclientException - if the operation fails

setMaxUnacked

int setMaxUnacked(int numOfMaxUnackedMsgs)
           throws SolclientException

Changes the maximum number of unacknowledged messages that may be received on the specified Flow. This function may only be used when the Flow has been created with FlowHandle.PROPERTIES.ACKMODE set to SolEnum.AckMode.CLIENT. When the maximum number of unacknowledged messages is reduced, messages in transit will still be received even if that causes the application to exceed the new limit of maximum number of unacknowledged messages. The maximum number of messages that may be in transit at any one time is the lesser of the current allowable unacknowledged messages and the Flow property FlowHandle.PROPERTIES.WINDOWSIZE. The current allowable unacknowledged messages is simply the difference between the current (that is, before calling this function) maximum number of acknowledged messages and the number of messages received that have not been acknowledged.

Parameters:

numOfMaxUnackedMsgs - - The new value for maximun number of acknowledged messages to allow on the Flow. If set to -1, there is no limit to the maximum number of acknowledged messages other than the Appliance defined limit in the endpoint.

Returns:

SolEnum.ReturnCode

Throws:

SolclientException - if the operation fails

getProperty

java.lang.String getProperty(java.lang.String flowPropertyName)
                      throws SolclientException

Gets the value of the specified Flow property for the Flow. The property value is returned in a String that is allocated for the applications use. When the application no longer references this String it will be garbage collected by the JavaVM. Consequently this method should not be used by applications that cannot tolerate JavaVM garbage collection.

Parameters:

flowPropertyName - FlowHandle.PROPERTIES

Returns:

the property value as a String

Throws:

SolclientException - if the operation fails