9
Oracle Message Broker C++ API

This chapter describes the Oracle Message Broker C++ API. Using the C++ API, clients written in C++ can use the Oracle Message Broker services and interoperate with clients written in Java.

The sample programs for the examples shown in this chapter are available in the directory, $OMB_HOME/samples/client/cpp.

This chapter covers the following:

• Introduction

• Major Differences between the Java and C++ APIs

• Sample Application

Introduction

The Oracle Message Broker provides a C++ API by defining a set of C++ classes that clone the JMS Java classes and interfaces (these are defined in the javax.jms package for Java). The C++ API uses the same names and follows the same class hierarchy as the JMS Java API counterparts. If you are a C++ programmer familiar with the JMS specification you do not need to learn a new API to use the Oracle Message Broker C++ API. However, you need to learn several conversion rules between Java and C++. This chapter covers the C++ API, and shows the conversion rules for working with the C++ API and the Oracle Message Broker.

System Requirements

To compile applications that use the Oracle Message Broker C++ API, you need to use an ISO C++ compiler (ISO/IEC FDIS 14882). In addition, the Oracle Message Broker C++ API requires support for the long long type (this type is not mandated by the ISO standard, but most compilers provide it). Some pre-ISO compilers may work, if they support namespaces, runtime type information, and the C++ Standard Template Library (STL).

Limitations

The Oracle Message Broker C++ API implements most of the features of the Java API, except:

• Only the TextMessage and BytesMessage classes are implemented. In BytesMessage, only the reset(), readByte(), readUnsignedByte(), readBytes(), writeByte(), and writeBytes() methods are implemented. Functions which are not implemented throw a NotImplementedException exception.

• Queues and topics cannot be fetched directly from the directory by a C++ application. They must be created using the createQueue() and createTopic() methods declared on sessions. The parameter to these methods is the distinguished name (dn) of the queue or topic in the directory. The Oracle Message Broker will use this name to fetch itself the queue or topic from the directory.

Major Differences between the Java and C++ APIs

Declaration

The Oracle Message Broker C++ API is declared in the scope of the "jms" C++ namespace. All the class declarations are imported by including the jmscpp.hh header file. An additional implementation-specific header file, ImplDepFactory.hh, must be included to obtain initial references to the Oracle Message Broker instance; once these initial references are obtained, only standard JMS constructs are used.

Types

While Java's basic types have well-specified sizes, the C++ specification is less restrictive concerning the size of built-in types. The Oracle Message Broker C++ API maps Java basic types to C++ basic types that have at least the same size, according to the ISO standard. Table 9-1 shows the mapping.

Table 9-1  Mapping Between Java and C++ Types

Java	C++
short	short
int	long
long	long long
float	float
double	double
byte	unsigned char
string	wstring (basic_string<wchar_t>)
byte[]	vector<unsigned char>

Memory Management

While Java has built-in garbage collection, the C++ programmer must explicitly allocate and deallocate memory. The rules for C++ memory management are as follows:

• Parameters passed by reference to a Oracle Message Broker C++ method are never deallocated by an Oracle Message Broker C++ library; they must be explicitly deallocated by the caller.

• Parameters passed by value by an Oracle Message Broker C++ method are copied during invocation and the caller is responsible for deallocating the original value; the Oracle Message Broker C++ library manages the life cycle of the copy.

• Parameters returned by reference by an Oracle Message Broker C++ method must be deallocated explicitly by the caller, even if they have been allocated by the Oracle Message Broker C++ library.

• Parameters returned by value by an Oracle Message Broker C++ method are copied during invocation and the caller is responsible for the returned copy's life cycle.

Sample Application

This section presents a sample Oracle Message Broker C++ application composed of two programs: a queue sender and a queue receiver. Most of the code for the sender and the receiver is similar. The code sections that differ are marked as sender or receiver specific.

Start the sender with arguments for the queue name and a text message. Start the receiver with a queue name. The queue name for the Oracle Message Broker C++ API is the dn of the queues entry in the directory. For example:

% sender cn=myQueue,cn=Queues,cn=MyOMB,cn=OMB,cn=Products,cn=OracleContext, 
ou=oas,o=oracle,c=us "Hello World!"
% receiver cn=myQueue,cn=Queues,cn=MyOMB,cn=OMB,cn=Products, cn=OracleContext, 
ou=oas,o=oracle,c=us 

General Declarations

Both the sender and the receiver code include the Oracle Message Broker C++ headers, and define a utility function for converting a C string into a wide string and printing a wide string to the console. This common code is as follows:

#include <jmscpp.hh>
#include <ImplDepFactory.hh>

wstring to_wstring(char *str)
{
  string s(str);
  wstring ws(s.length(), ' ');
  copy(s.begin(), s.end(), ws.begin());
  return ws;
}

ostream& operator <<(ostream& os, const wstring& ws)
{
  copy(ws.begin(), ws.end(), ostream_iterator<char>(os));
  return os;
}

Initialization

The sender and the receiver first obtain a reference to an Oracle Message Broker specific ImplDepFactory object that creates a JMS connection factory. There are two different constructors for the ImplDepFactory object:

  ImplDepFactory(const wstring& ior_file, const wstring& driver_name,
                 bool unused, const wstring& cid, long priority, 
                 long tx_timeout);

Where the arguments are as follows:

ior_file	The name of a file that contains the Oracle Message Broker IOR. This IOR can be obtained from the msg_broker entry in the directory or from the Oracle Message Broker log file.
driver_name	The driver name, this can be one of: vol, aq, mq, mcast, rv.
unused	An unused boolean value.
cid	Arbitrary name identifying of the client
priority	Default priority of messages
tx_timeout	Default transaction timeout

  ImplDepFactory(const wstring& provider_ior, const wstring& driver_name,
                 const wstring& cid, long priority, long tx_timeout);

Where the arguments are as follows:

provider_ior	The Oracle Message Broker IOR. This IOR can be obtained from the msg_broker entry in the directory or from the Oracle Message Broker log file.
driver_name	The driver name, this can be one of: vol, aq, mq, mcast, rv.
cid	Arbitrary name identifying of the client
priority	Default priority of messages
tx_timeout	Default transaction timeout

C++ applications can fetch the Oracle Message Broker IOR directly from the directory using OID's LDAP C libraries. A sample program that performs this task is included with the C++ samples.

The sender and the receiver next create a queue connection factory, a queue connection, a queue session, a queue, and finally start the connection.

The following code shows these steps.

int main(int argc, char **argv)
{
  try {
    ImplDepFactory idf(L"JMSProvider", L"vol", true, L"client", 4, 0);
    QueueConnectionFactory *cf = idf.createQueueConnectionFactory();

    // Create connection and session
    QueueConnection *conn = cf->createQueueConnection();
    QueueSession *sess = conn->createQueueSession(false, 
          Session::IMMEDIATE_ACKNOWLEDGE);
    Queue *queue = sess->createQueue(to_wstring(argv[1]));

    // Start connection
    conn->start();
    }
}

Sending Messages (Sender Specific)

The queue sender creates a sender, constructs a text message, and sends the text message using the sender. The message and the sender are then explicitly deallocated.

    // Sender-specific code
    QueueSender *sender = sess->createSender(queue);
    // Create and send message
    Message *msg = sess->createTextMessage(to_wstring(argv[2]));
    sender->send(msg);
    sender->close();
    delete msg;
    delete sender;

Receiving Messages (Receiver Specific)

The queue receiver creates a receiver, waits for a text message, prints the text message, closes the receiver, and deallocates the message and the receiver.

    // Receiver-specific code
    QueueReceiver *receiver = sess->createReceiver(queue);
    // Receive message
    Message *msg = receiver->receive();
    TextMessage *tm = dynamic_cast<TextMessage*>(msg);
    if(tm != NULL)
      cout << "Received message: " << tm->getText() << endl;
    receiver->close();
    delete msg;
    delete receiver;

Cleanup

Finally, the sender and the receiver close open sessions and connections, and deallocate all Oracle Message Broker C++ objects.

    conn->stop();
    sess->close();
    conn->close();
    delete queue;
    delete sess;
    delete conn;
    delete cf;
  } catch(JMSException e) {
    cerr << "Unexpected exception: " << e.getMessage() << endl;
  }
  return 0;
}