SolaceSystems.Solclient.Messaging Namespace

Some Session Properties can also be set as environment variables. If a session property can be set as an environment variable, the API will only look for that environment variable if the property is not specified in the sesssion property list passed to CreateSession(SessionProperties, EventHandlerMessageEventArgs, EventHandlerSessionEventArgs)

The names of the environment variables are based on the native library property names.

The following environment variables are recognized:

• SOLCLIENT_SESSION_PROP_PASSWORD Password
• SOLCLIENT_SESSION_PROP_HOST Host
• SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION GdReconnectFailAction The acceptable strings for this environment variable are also based on the underlying native library:
  1. "SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION_AUTO_RETRY" (AUTO_RETRY)
  2. "SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION_DISCONNECT" (DISCONNECT)

To acquire an IClientName instance, applications must call CreateClientName(String)

To add or remove subscriptions on behalf of a remote client, applications must call Subscribe(IEndpoint, ISubscription, Int32, Object) and Unsubscribe(IEndpoint, ISubscription, Int32, Object) respectively.

A context is an active object that initializes and manages its own thread. The life cycle of the owned thread is bound to the life cycle of the context. A context-owned thread drives I/O and notification events of registered delegates of the context.

All callbacks (or delegate invocation) from the API to the application, message receive callbacks, event callback, and timer callbacks, run from the context thread. Additionally the context thread must run to detect relief from flow control and unblock waiting application threads. The context thread must run to complete the session connection sequence and unblock applications waiting for connection complete. The context thread must run to unblock applications waiting for confirmation on subscription requests. Consequently, applications must not block in callback/delegate routines. Waiting in callback routines can deadlock the application or at a minimum severely degrade receive performance. Deferring SolClient processing by running for excessively long periods of time in the callback routines prevents the API from unblocking other application threads that might be waiting for confirmation of sent messages, or blocked in flow control situations.

Important: Disposing a context must not be performed in a context callback delegate for the context being disposed. This includes all sessions(ISession), flows(IFlow) and timers (TimerTask) on the context.

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

Client applications must dispose of messages (by calling Dispose()) as soon as they are done with them.

Note: Unless indicated otherwise, mutable IMessage's properties are accessed and assigned by value and not by reference. In other words, the property's getter returns a copy of the IMessage's mutable internal state and its setter takes a copy of the passed in mutable value.

In the typical scenarios, using Subscribe(ISubscription, Boolean) , CreateFlow(FlowProperties, IEndpoint, ISubscription, EventHandlerMessageEventArgs, EventHandlerFlowEventArgs) or CreateFlow(FlowProperties, IEndpoint, ISubscription, EventHandlerMessageEventArgs, EventHandlerFlowEventArgs, EndpointProperties) client applications can register interest to receive messages with destinations matching the set of added subscription(s). All matching messages are received within the context of the message callback delegate. There's one delegate registered per session or flow.

IMessageDispatcher is an interface abstraction which enables the API to further demultiplex messages to consumers based on registered subscriptions (within aISession or IFlow). Dispatching/demultiplexing incoming messages based on topics allows different callback delegates to be invoked based on the received message's topic. Full wildcard subscription syntax is supported see ITopic for more details.

To better illustrate the usage of this feature, consider the following examples: A client application registers interest to receive messages matching 'car/>', it does so by calling the Subscribe method on an ISession instance. All messages matching this wildcard topic are received over the message callback delegate. In this case, the client receives any message matching 'car/>', for example: 'car/gmc' or 'car/toyota' Using the Topic dispatch feature, the client application (as described above) can demultiplex incoming messages to different callback delegates. For example, it can create a couple of IDispatchTarget instances; the first one with 'car/gmc' as topic subscription and the second with 'car/toyota'. Then it can call the ISession's Subscribe(IDispatchTarget...) method to add these subscriptions along with the delegates to invoke when receiving matching messages on 'car/gmc' or 'car/toyota'. Delivered message with destinations outside of these two topic subscriptions, are still received over the default message callback delegate associated with the ISession instance.

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

Disposing a session must not be performed in a session callback delegate for the session being disposed. This includes all flows on the session.

Supported Topic Syntax

Supported Subscription Syntax

• If messages are received over the message dispatcher thread (async), client applications must invoke commit/rollback/sendMsg from the context of that thread (i.e. in the context of the message dispatcher thread CreateMessageDispatcher).
• If messages are received from an application thread by calling ReceiveMsg(Int32) directly, commit/rollback/sendMsg/receiveMsg functions must be called in the context of the same application thread.

The Class of Service has different semantics for direct and guaranteed messages. For direct messaging, it determines the WRR weight for the message. For guaranteed messaging, it indicates the discard eligibility of the message if the endpoint is congested (see LowPriorityMsgCongestion)