3.6 Transferring Data Over an ORB Connection

To pass an object by value using the Orbix opaque mechanism, you need to write marshaling functions that prepare instances of your classes for transmission through the ORB, and unmarshaling functions that create new instances on the other side. Tools.h++ Professional eases this tedious and error-prone process.

There are two different techniques for passing objects across the wire: one for classes that define virtual stream shift operators, and another for classes that inherit from RWCollectable.

3.6.1 Classes that Define Virtual Stream Shift Operators

After you write operators that shift instances of your class to and from virtual streams, you must prepare instances to be passed by value. To do this, you invoke the RWDEFINE_OPAQUE macro, supplying the name of your class:

#include <rw/toolpro/opaqueio.h>
RWDEFINE_OPAQUE(MyClass)

This macro expands to the necessary marshaling and unmarshaling functions, which create and use instances of the RWreqistream and RWreqostream classes. Figure 4 shows the relationship between the RWvistream, RWreqistream, and CORBA::Request classes.

Figure 4 -- Relationships between RWvistream, RWrequistream, and CORBA::Request classes

The unmarshaling function created by RWDEFINE_OPAQUE accepts a CORBA::Request as an argument, and creates an RWreqistream from it. The unmarshaling function then creates an object by shifting its contents from the RWreqistream virtual stream.

3.6.2 Classes that Derive from RWCollectable

An analogous macro exists for classes derived from RWCollectable:

#include <rw/toolpro/opaqueio.h>
RWDEFINE_OPAQUE_COLLECTABLE(MyCollectableClass)

This generates functions that also use RWreqistream and RWreqostream, but use RWCollectable::saveGuts() and RWCollectable::restoreGuts() instead of the shift operators.

3.6.3 Deciding Which Classes To Use

Should you create classes that define virtual stream shift operators, or should you create RWCollectable subclasses? That depends. If you plan to take advantage of the polymorphic persistence machinery offered by the Smalltalk-like collections in Tools.h++, by all means take the extra steps necessary to create an RWCollectable subclass. Otherwise, just define virtual stream helper functions-they'll let you use your class with all the Tools.h++ and Tools.h++ Professional streams classes.

See the orbs/dog, orbs/roster, and library example directories for sample code that uses the RWDEFINE_OPAQUE and RWDEFINE_OPAQUE_COLLECTABLE macros. The library example also uses an RWJObjectOutputStream to send data retrieved from a remote ORB to a Java client application.