Solace Java RTO API Concepts

The Solace Messaging API for Java RTO is designed with core messaging concepts, and it uses fundamental components to process messages and data. Understanding how the Solace Java RTO API uses these components, and how they relate to each other, is necessary to develop applications to send and receive messages over Solace event brokers.

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

Messaging Domains

The Solace Java RTO 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 Java RTO APII 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
  • 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 and 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?

Messages exchanged between the Solace Java RTO API have formats that are compatible across all Solace Messaging APIs. In other words, messages produced by one Solace Messaging API can be understood by any other consuming Solace Messaging API.

In the Solace Java RTO API, a message is represented as:

com.solacesystems.solclientj.core.handle.MessageHandle

Factories

As a programming interface for an object-oriented language, the Solace Java RTO API uses a singleton factory as the first point of contact. 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.

Factory API

In the Solace Java RTO API, use com.solacesystems.solclientj.core.Solclient as the factory API.

Contexts

The Solace Java RTO 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. For the Solace Java RTO 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 APIs

In the Solace Java RTO API, use com.solacesystems.solclientj.core.handle.ContextHandle

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 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.

Session API

In the Solace Java RTO API, use com.solacesystems.solclientj.core.handle.SessionHandle

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

Session and its Aggregates

Handles

Handles are used in the Solace Java RTO API. The Solace Java RTO API is an implementation of Java Native Interface (JNI)-wrapped C, and is essentially an object-oriented abstraction of the C API.

A handle is a Java interface representing a C object. Handles are created by Solclient.Allocator and are unbound (not associated with any C object) when created. Handles can be bound to (associated with) a C object through the Solace Java RTO API.

When a handle is bound to a C object, that C object can be manipulated through the Solace Java RTO API.

Handles have the word Handle appended to their class name, as in ContextHandle or MessageHandle.

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.

The cache session call for the Solace Java RTO API is com.solacesystems.solclientj.core.handle.CacheSessionHandle