Solace .NET API Concepts

The Solace .NET API is designed with core concepts and fundamental components to process messages and data. Understanding how the Solace .NET API uses these components, and how they relate to each other, is necessary to develop applications to send and receive messages over Solace products.

This section provides an introduction to these core concepts and processing components.

Messaging Domains

The Solace .NET API supports both point-to-point (PTP) and publish and subscribe (Pub/Sub) messaging domains.

  • point-to-point

    PTP messaging is built around the concept of message queues that clients can publish messages to. Each message is addressed to a specific queue. Consuming clients can also extract messages from queues that hold messages for them.

  • publish and subscribe

    Pub/Sub clients address messages to some node in a content hierarchy. These nodes are defined topics. Publishers and subscribers are generally anonymous and may dynamically publish or subscribe to the content hierarchy. The Solace message bus distributes the messages published to a node to those clients that have subscribed to the same node.

The Solace .NET API provides many features, including:

  • connection management to Solace event brokers
  • addition and removal of topic-based subscriptions
  • sending and receiving messages (blocking and non-blocking)
  • Direct and Guaranteed message delivery modes
  • structured data types that do not rely on a specific architecture or programming language
  • extensive support for logging and customizing through property parameters
  • request/reply messaging support
  • queue browser support
  • Solace Cache client API support

Messages

A message is a packet of information sent from producers to consumers. Messages are the central units of information that clients exchange over Solace event brokers. Solace uses the Solace Message Format (SMF) protocol for client and event broker communications. SMF uses a proprietary binary message format that provides an efficient method of encapsulating messages for transmission over the platform. For information on message parts, see What Is Messaging?

In the Solace .NET API, a message is represented by:

SolaceSystems.Solclient.Messaging.IMessage

Factories

The Solace .NET API uses a singleton factory as the first point of contact to the API. A factory is used to obtain instances of messaging system entities such as contexts, sessions, non-temporary destinations, durable endpoint instances, and subscriptions. It is also used to configure global properties, and it exposes a number of useful statistics at the message and memory pool levels.

In the Solace .NET API, the factory is:

solacesystems.Solclient.Messaging.ContextFactory

Contexts

The Solace .NET API uses processing contexts for organizing communication between an application and a Solace event broker. Contexts act as containers in which sessions are created and session-related events can be handled.

A context encapsulates threads that drive network I/O and message delivery notification for the sessions and session components associated with that context. In the Solace .NET API, a single thread is used for both I/O and for notification. The life cycle of a context‑owned thread is bound to the life cycle of the context.

Context API

In the Solace .NET API, contexts are accessed through:

SolaceSystems.Solclient.Messaging.ContextFactory

SolaceSystems.Solclient.Messaging.IContext

The figure below shows the basic relationship between a context and its dependent processing components.

Overview of Core Concepts

Sessions

When a context is established, one or more sessions can be created within that context. A session creates a single, client connection to an event broker for sending and receiving messages.

A session provides the following primary services:

  • client connection
  • update and retrieve session properties
  • retrieve session statistics
  • add and remove subscriptions
  • create destinations and endpoints
  • publish and receive Direct messages
  • publish Guaranteed messages
  • make requests/replies
  • create Guaranteed message flows to receive Guaranteed messages
  • create browsers
  • create cache sessions

When configuring a session, the following must be provided:

  • Session properties to define the operating characteristics of the client connection to the event broker.
  • A message callback for Direct messages that are received.
  • An event handling callback for events that occur for the session.

In the Solace .NET API, sessions are represented by the SolaceSystems.Solclient.Messaging.ISession interface.

The figure below shows some of the fundamental processing components that are dependent on a session.

Session and its Aggregates

Cache Sessions

If you want your application to be able to send and receive requests for cached messages for a topic of interest, you must create one or more cache session objects in a session. A session can support multiple cache session objects.

The Solace Cache feature is only available to sessions connected to an event broker that has implemented Solace Cache.

To create a cache session in the Solace .NET API, use:

SolaceSystems.Solclient.Messaging.ICacheSession