10.27.03

IFlow Interface

A flow is an API concept that allows the application to receive messages from an endpoint on the appliance (a IQueue or ITopicEndpoint on a Solace appliance running SolOS-TR). Flows are not used by clients that receive Direct messages. Rather, Direct messages are received by clients with matching subscriptions directly from the appliance’s message bus through sessions instead of binding to a specific endpoint on the message bus.

Disposing a flow must not be performed in the flow callback delegate of the flow being disposed.

Definition

Namespace: SolaceSystems.Solclient.Messaging
Assembly: SolaceSystems.Solclient.Messaging (in SolaceSystems.Solclient.Messaging.dll) Version: 10.27.0
C#
public interface IFlow : IDisposable, IStatsAccessible, 
	IMessageDispatcher
Implements
IMessageDispatcher, IStatsAccessible, IDisposable

Properties

Properties Returns a copy of the Flow properties

Methods

Ack Sends an acknowledgement for a message received over this flow.

This instructs the API to consider the specified ADMessageId 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.

The exact behavior of Ack() is controlled by flow property MessageAckMode:

  • AutoAck - Messages are acknowledged automatically by the API and calling this function has no effect.
  • ClientAck - Every message received must be acknowledged by the application through individual calls to Ack().

When the transport is flow controlled (for example, the application is overwhelming the underlying tcp connection), if it is not possible for the API to block until the congestion is relieved, the call to this method will return SOLCLIENT_WOULD_BLOCK on sessions configured with SendBlocking set to false. The session event callback delegate will receive a subsequent CanSend when the congestion is relieved. On sessions configured with SendBlocking set to true, the call to this method, will block until the congestion is relieved unless this is not possible (due to to the fact that the this method is called from a callback delegate). If it's not possible to block, this method will return SOLCLIENT_FAIL with a subcode of CannotBlockInContext

In practice this occurs very rarely as most applications do not simulteously publish and receive large amounts of data on the same session. On sessions that primarily receive data, sending acknowledgements alone cannot generate enough traffic to overwhelm the tcp connection.

Ack is equivalent to Settle(Int64, MessageOutcome) with message outcome Accepted.


ClearStats Clears the stats dictionary.
(Inherited from IStatsAccessible)
CreateDispatchTarget Creates a IDispatchTarget instance to be used in the Subscribe(IDispatchTarget, Int32, Object) and Unsubscribe(IDispatchTarget, Int32, Object) methods.

Note: Client applications must keep IDispatchTarget object references accessible if they want to Unsubscribe from the given IMessageDispatcher, and remove already added Topic subscriptions. IDispatchTarget internal object ID constitutes a unique key. Forgetting to keep a reference to IDispatchTarget objects make subsequent Unsubscribe(IDispatchTarget, Int32, Object) calls impossible.


(Inherited from IMessageDispatcher)
DisposePerforms application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
(Inherited from IDisposable)
GetDestination Returns the IDestination to which messages should be published to get to this flow's bound IEndpoint

If bound to a ITopicEndpoint, the returned IDestination will be of type ITopic

If bound to a IQueue, the returned IDestination will be of type IQueue

Otherwise, a null is returned

GetEndpoint Returns a reference to the Endpoint which this flow is bound to.

Possible endpoints include ITopicEndpoint or IQueue

Endpoints can be durable or non-durable. Durable endpoints must be explicitly created through CreateDurableTopicEndpointEx(String) or CreateQueue(String).

Non-durable endpoints are implicitly created after creating the flow and connecting the parent session, therefore calling this method before the parent ISession is connected will throw an OperationErrorException.

Note that IQueue is both an IEndpoint and IDestination, so it has both the durability ( see Durable ) and temporariness (see Temporary ) properties.

GetRxStats Returns the Rx Stats.
(Inherited from IStatsAccessible)
GetSession Returns a reference to the ISession that was used to create this flow.
GetSubscription Returns a reference to a ITopic subscription instance.

Similar to Non-durable endpoints, temporary destinations returned by this method are implicitly created after the flow is created and parent session is connected.

GetTransactedSession Returns a reference to the Transacted Sesion asociated to the Flow.
GetTxStats Returns the Tx Stats.
(Inherited from IStatsAccessible)
ReceiveMsg Receives a message from a specified transacted Flow. It waits until a timeout or a message is received. No wait if timeout is zero. Applications must later call .Dispose() on the received message to release it.
Settle Settles a message in a requested way. See Also Ack(Int64).

Settle has 3 message outcome options:

  • Accepted - The message was succesfully processed (the same as Ack(Int64)).
  • Failed - The message will be redelivered.
  • Rejected - The message is removed from the queue and moved to the DMQ if configured.

The exact behavior of Settle() is controlled by flow property MessageAckMode:

  • AutoAck - Messages are acknowledged automatically by the API and calling this function has no effect.
  • ClientAck - Every message received must be acknowledged by the application through individual calls to Settle().

Settle requires RequiredOutcomeFailed and/or RequiredOutcomeRejected to be enabled to allow "Failed" and/or "Rejected" outcomes, respectively.

Start Starts the transport window of the flow enabling it to receive messages. When a IFlow is first created, it is already started, unless FlowStartState is set to false.

To restart a flow after it is been stopped (see Stop), clients must call start on the stopped flow.

Stop Stops or closes the transport window resulting in the eventual halt of message delivery. Stopping a flow does not result in message loss. It simply "pauses" message delivery until Start() is called again.

To restart a flow after it is been stopped, clients must call Start on the stopped flow.

Subscribe Adds a IDispatchTarget subscription to the given IMessageDispatcher.

Note: In order to use this feature, the parent ISession's SessionProperties must have TopicDispatch set to true.


(Inherited from IMessageDispatcher)
Unsubscribe Removes an IDispatchTarget subscription from the given IMessageDispatcher.

Note: To use this feature, the parent ISession's SessionProperties must have TopicDispatch set to true.


(Inherited from IMessageDispatcher)

See Also