27.2 Passing User-Defined Objects

As discussed in Chapter 26, the orb library helps you pass Rogue Wave and user-defined objects, as opaque types in an IDL operation. To help you understand how the orb library works, this section shows how you would use opaque to pass user-defined objects without the orb library.

27.2.1 Defining an Object as an Opaque Type

To pass a user-defined type in an interface using the opaque mechanism, you define the object as an opaque type in the IDL file. For example, given an interface called Library and two C++ classes, Book and Borrower, an IDL file might be written as follows:

opaque Book;
opaque Borrower;
interface Library
{
  boolean checkOut(in Book bk, in Borrower brwr);
  void checkIn(in Book b);
  // and so on
};

The checkOut() operation takes two opaque objects as in parameters. The checkIn() operation takes a single opaque object as an in parameter.

27.2.2 Insertion and Extraction Operators

In the Library example that we introduced above, Orbix requires the developer to create the following insertion and extraction operator functions for Book, and a similar set for Borrower.

CORBA::Request &operator<<(CORBA::Request &req, const Book *bk);
CORBA::Request &operator<<(CORBA::Request &req, Book *&bk);
CORBA::Request &operator>>(CORBA::Request &req, Book *&bk);

As we will see in the next section, Orbix requires all opaque objects to provide these operator functions. Section 27.3, "Writing to a Virtual Stream Instead of a CORBA::Request," shows how the orb library simplifies this task by providing classes and macros that expand to the appropriate insertion and extraction operations.

27.2.3 Communicating an Object's State with a CORBA::Request

To pass the Book and Borrower objects by value, you must tell the ORB how to pass the state of these objects. In the C++ code, this is accomplished by writing insertion and extraction operators to communicate the state of an object to and from a CORBA::Request.

A CORBA::Request can be thought of as an object that packages an operation and its arguments for the trip across the wire, or address space boundary, to the remote object. It also brings back any return arguments that you might be expecting from the remote method invocation.

Figure 30 -- The role of a CORBA::Request

Orbix provides a public C++ interface for the Request that allows you to save or restore the state of an object directly to and from the Request object. If you can describe the object's state in terms of simple IDL types, you can pass it using this mechanism. You describe how to save and restore your object by writing insertion and extraction operators for it, to and from the CORBA::Request. Orbix calls these functions when it is appropriate for you to save or restore the state of your object.