Oracle Message Broker Adminstration Guide Release 2.0.1.0 Part Number A65435-01 |
|
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:
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.
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).
The Oracle Message Broker C++ API implements most of the features of the Java API, except:
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.
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.
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.
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.
Java | C++ |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
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
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; }
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:
ImplDepFactory(const wstring& provider_ior, const wstring& driver_name, const wstring& cid, long priority, long tx_timeout);
Where the arguments are as follows:
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(); } }
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;
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;
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; }
|
![]() Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|