HORB Serialization Patch
Alpha version 1.2a

What's New

• Bug fix: Fixed SerializingIOCI bug re: using Serialization for returning server-side objects.
• In earlier versions, the ObjectOutputStream is not reset when sending objects as return values.  Thus, when the same object is returned twice to the same client, it does not get re-sent the second time -- even if its contents have changed.  This results in a hard-to-catch bug, where clients do not get the desired updated versions of server-side objects.  See v11bug example.
• Bug fix: Fixed horbc bug re: classes that have static variables.
• In earlier versions of the patch, using a remote object which has static or private fields resulted in a null-pointer exception.  This was because the horbc compiler did not generate correct code for instantiating the object.  This problem was fixed by undoing some changes in horbc\Skeleton.java
• Array performance patch.  Incorporated fixed "Hirano+Takagi" performance patch to BasicIOCI.java for primitive arrays transfers that do not use JDK serialization.  See passArray example.
• Clarification:  Contrary to the v1.1a documentation.  You can have Serializable components of non-Serializable data.  See passMixed example.

Features

• Removes the need to run horbc on objects that are only used as parameters or return values of remote functions.
• Enables HORB applications to use built-in objects that implement Serializable (e.g., java.util.Vector).
• Backwards-compatible (see known limitations below)
• works with non-Serializable data and mixed-mode data (requires horbc)
• new clients can connect to old servers
• new servers can accept connections from old clients
• automatically uses built-in Serialization when available; uses old HORB serialization otherwise
• Improved performance for primitive arrays transfers (when not using Serialization).

Files

Files under horb\classsrc

Modified classes

• horbc\Proxy.java
• orb\BasicIOCI.java
• orb\HORB.java
• orb\HORBSerializable.java
• orb\HorbURL.java
• orb\IOCICommon.java
• orb\Proxy.java

New classes

• orb\SerializingIOCI.java
• orb\HORBObjectInputStream.java
• orb\HORBObjectOutputStream.java

Code snippets

• orb\HookSerializer.java -- insert this in files that use _freezeHook() and _reviveHook()

Unrelated modified/new classes

• orb\HasSerialHooks.java -- interface for _freezeHook() and _reviveHook() (currently unused)
• orb\HasThreadEndHook.java -- interface for _threadEndHook()
• horbc\Skeleton.java -- fixed so _threadEndHook() can be inherited.
• orb\Skeleton.java -- has small fixes by Hirano-san (I don't know what they do)
• orb\HORBServer.java -- has small fixes by Hirano-san (I don't know what they do)

Example directories under horb\examples\serialization\

• passObj -- demonstrates passing non-Serializable, mixed-mode, and Serializable data; also demonstrates hooks
• passVector -- demonstrates passing java.util.Vector and java.util.Hashtable
• passRef -- demonstrates passing remote references using Serialization
• complex -- demonstrates passing complex objects using Serialization
• v11bug -- demonstrates the bug in v1.1a of the patch and shows this bug to be fixed in v1.2a
• passMixed -- demonstrates the use of Serializable fields of non-Serializable objects.
• passArray -- demonstrates and tests primitive array transfers.  Serves as correctness-test for performance patch.

Other files under horb\serpatch\

• Serialization.html -- this file
• BasicIOCI.java.s10 -- the v1.0a version of this file.  Modified for the Serialization patch, but without the Hirano+Takagi array performance patch.  Replace orb/BasicIOCI with this and recompile ("java -O -d ..\..\.. BasicIOCI.java") if you don't want the performance patch.
• serpatchlog.txt -- Development log started midway through development of v1.2a release.  In the future, this will contain development notes that may be useful to those who want to modify or understand the patch.

How to Use

1. Unzipping the files. Download the file horbs12.zip and unzip in the horb directory.  The files listed above should be created in their respective subdirectories. The class files should be created in corresponding subdir under horb (i.e., horb\orb and horb\horbc).
2. Using Serializable objects. If you have an object that is only used as a parameter or return value, and whose methods are not called remotely, then you don't need to run horbc on it. Simply add implements java.io.Serializable to the class definition. (If you need to call some methods of your object remotely, you still need to run horbc.)
3. Enabling Serialization on the Server.

From the command-line, instead of simply entering:
   >horb
instead enter
   >horb -ioci horb.orb.SerializingIOCI
to tell HORB to use SerializingIOCI instead of the normal BasicIOCI.

If you are starting a HORBServer within an application instead of the command-line, add the line
   horb.orb.HORB.useSerialization();
before you start the HORBServer. This will enable Serialization if available.

4. Enabling Serialization on the Client.

Before creating any Proxy's or connecting to any server, add:
   horb.orb.HORB.useSerialization();
5. Using non-Serializable objects. Compile with horbc as with original HORB.
6. Using mixed-mode objects. Add implements java.io.Serializable to the class definition and compile with horbc as well. Such objects will use built-in Serialization if available, but will use HORB serialization otherwise. (If you do not compile with horbc, then your code will only work with JDK 1.1 and above.)
7. Using hooks. You can use _freezeHook() and _reviveHook() as before. However, if you use them in a Serializable object, you must define readObject() and writeObject() methods to call the hooks. You can do this by simply insert the file HookSerializer.java into your code.
8. Using horb.orb.HORBSerializable.  Some basic HORB classes (specifically horb.orb.Proxy and horb.orb.HorbURL) are now Serializable.  However, for more backward-compatibility, they do not extend/implement java.io.Serializable directly, but instead implement horb.orb.HORBSerializable which extends java.io.Serializable.  If you are using an old version of Java and are having problems compiling code, edit HORBSerializable to make it extend nothing, and then recompile HORBSerializable.
9. Serializing Primitive Arrays.  By default, SerializingIOCI uses Serialization, if available, for transferring arrays of primitive types.  You can change this default by calling horb.orb.HORB.useSerialization(arg) where the boolean arg is set to true to turn on JDK Serialization of primitive arrays (default), or false to turn primitive array Serialization off.  In general, it is best if you do this on both the server and the client.  (More specifically, a receiver with array serialization turned on can accept arrays with or without serialization, but a sender with array serialization turned on must have a receiver with array serialization turned on as well.)

 Known Limitations

• Currently, without JDK Serialization, HORB (even with or without the patch) cannot send arrays assigned to Object-type references (e.g., arrays added to a Hashtable).  Turning on JDK Serialization will transparently fix this problem (since arrays are Serializable).  However, we should still fix this problem, since it may be preferrable to use HORB instead of JDK Serialization for array transfers due to better performance.
• Backwards compatibility doesn't always seem to work.  For example, in Netscape 3.04 on Solaris and Linux, using Serializable or mixed-mode objects results in a java.lang.SecurityException as the applet ClassLoader loads the class (try the passObj example to see). It is not clear why this happens in this example while it generally does not happen with *_Proxy objects, which also implement java.io.Serializable (via horb.orb.HORBSerializable).  Using horb.orb.HORBSerializable instead (like Proxy's do) doesn't seem to solve this problem either.
• Proxy objects now use the readObject(ObjectInputStream) and writeObject(ObjectOutputStream) methods, so you can't define remote methods with these names.
• Access Control should work, but not yet fully tested. Especially needs to be tested with remote references.
• Caution: The code given here is based on a version of the source code dated around Jan. 1998.  It may not contain the latest performance patches and bug fixes. If you are concerned about this, please save your current source files somewhere else and do a diff before replacing your files.

History

Alpha releases

• v 1.2a (981203) -- bug fixes and primitive array performance patch
• v 1.1a (980715) -- added serialization of primitive arrays
• v 1.0a (980707) -- original release

Future Work

• Allow HORB (without Serialization) to pass arrays assigned to Object-type references (e.g., arrays in Hashtables).
• Use JDK Serialization for arrays of Serializable objects.  (Currently, arrays of Serializable objects are Serialized individually by a for loop in the remote method's proxy.)
• Performance evaluation.  We did some performance evaluation for the CHEP98 paper.  It seems to show that HORB is faster than Serialization, especially for arrays or chains of non-primitive objects.  However, it may be useful to do more rigid and comprehensive tests.
• Fix the compatibility problems.  (Is this at all possible?)
• More testing and examples.
• Merge with other patches?  (As far as I know, this incorporates all publicly announced patches to date.  But I could be wrong.)
• Better documentation?
• Other bug fixes?

Disclaimer