Native C++RTL Guide

The  C++Runtime Library (C++RTL) allows C++ based application to inter­act with FioranoMQ. A C++ based client can thus seamlessly communicate with Java based Fiorano Clients. This version of C++RTL is designed to run on both native and .NET platforms. Both versions support secure and non-secure TCP and HTTP connections on Win32 platform for Point-to-Point and Publish/Subscribe communication models. The C++ Runtime is designed to provide maximum conformance with the JMS specifications. All public APIs have similar signature as the corresponding java APIs specified by JMS. The classes have a similar naming convention. 

Messaging Domains

There are two kinds of messaging domains:

1. Point-to-Point (PTP)
2. Publish-Subscribe(Pub/Sub)

In PTP domains, messages are sent to a particular destination where they are queued. A client application delivers messages from this queue to the destination specified by the provider. Though there can be several messages in the queue, each message is intended for only one destination/receiver. 
The Pub/Sub domain, on the other hand, allows a message to be distributed to more than one subscriber via the provider. 
Both these domains can be deployed by FioranoMQ. In addition, FioranoMQ can handle the unified domains introduced by JMS 1.1.
The JMS common interface provides a domain-independent view of the PTP and Pub/Sub messaging domains. Following are the list of JMS concepts with brief definition:

Connection Factory

As per JMS specifications, an application uses a Connection Factory to fetch the details of a connection instance to connect to the Server. The connection factory instance encapsulates all the parameters (like URL, protocol, and so on) required to connect to the Server. These parameters are configured to use the default socket acceptor settings and must be modified if the Server uses a socket acceptor with a non-default configuration. The Server creates the default connection factories when it is launched for the first time. These connection factories are automatically created based on the configuration of the socket acceptor being used.

Connection

A connection object is a client's active connection to its JMS provider. A connection could represent an open TCP/IP socket between a client and a service provider domain. Connections support concurrent use. You use a connection to create one or more sessions. Connections can be created specific to PTP and PubSub messaging styles. For example, CQueueConnection class can be used for Queue connection type and CTopicConnection class for Topic connection. 

Destination

A destination is the object which a client uses to specify the target of messages it produces and the source of messages it consumes. In the PTP messaging domain, destinations are called Queues, and in the pub/sub messaging domain, destinations are called Topics.

Session

A session is the single-thread context for producing and consuming messages. It can create and serve multiple Producers and Consumers.

A session can be either transacted or non-transacted. Each session supports a single series of transactions and treats them as a unit. Messages produced and consumed within a transaction become the content of that particular transaction. A commit method indicates that message processing can occur. A rollback method disables the processing of messages. In both cases, a transaction is considered to have been completed. A non-transacted session receives message in a mode specified by JMS 1.1: This mode could be one of the following modes: AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, and DUPS_OK_ACKNOWLEDGE. The DUPS_OK_ACKNOWLEDGE is used in applications where messages delivery can be duplicated.

JMS Message

The ultimate purpose of a JMS application is to produce and to consume messages that can then be used by other software applications. JMS messages have a basic format that is simple but highly flexible, allowing you to create messages that match formats used by non-JMS applications on heterogeneous platforms. A JMS message has three parts:

1. A header
2. Properties (optional)
3. A body (optional)

Message Producer

A message producer is an object created by a session and is used for sending messages to a destination. The PTP form of a message producer implements the CQueueSender interface. The pub/sub form implements the CTopicPublisher interface. You can create an unidentified producer by specifying null as the argument to createSender or createPublisher. With an unidentified producer, you can wait to specify which destination to send the message to, until you send or publish a message.

Message Consumer

A message consumer is an object created by a session and is used for receiving messages sent to a destination. A message consumer allows a JMS client to register interest in a destination with a JMS provider. The JMS provider manages the delivery of messages from a destination to the registered consumers of the destination. The PTP form of message consumer implements the CQueueReceiver class. The pub/sub form implements the CTopicSubscriber class.

The following diagram illustrates the flow of a JMS client.

C++RTL specific Data types and Constants, Error handling, Dot Net, API References, Sample Programs, and FAQs are covered in the following sections: