README for the "javaserial" example directory.
[$Id: README,v 1.10 1998/10/09 16:59:11 spreitze Exp $
 BeginILUCopyright

 Copyright (c) 1991-1998 Xerox Corporation.  All Rights Reserved.

 Unlimited use, reproduction, modification, and distribution of this
 software and modified versions thereof is permitted.  Permission is
 granted to make derivative works from this software or a modified
 version thereof.  Any copy of this software, a modified version
 thereof, or a derivative work must include both the above copyright
 notice of Xerox Corporation and this paragraph.  Any distribution of
 this software, a modified version thereof, or a derivative work must
 comply with all applicable United States export control laws.  This
 software is made available AS IS, and XEROX CORPORATION DISCLAIMS ALL
 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE
 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 PURPOSE, AND NOTWITHSTANDING ANY OTHER PROVISION CONTAINED HEREIN, ANY
 LIABILITY FOR DAMAGES RESULTING FROM THE SOFTWARE OR ITS USE IS
 EXPRESSLY DISCLAIMED, WHETHER ARISING IN CONTRACT, TORT (INCLUDING
 NEGLIGENCE) OR STRICT LIABILITY, EVEN IF XEROX CORPORATION IS ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGES.

 EndILUCopyright ]


This directory contains a simple example which use java serialization.  
This example also shows how to use both "custom mapping" and 
"custom records" in Java.

Let me add the caveat that I think it is more useful to establish a byte 
code server and load code from the server.  Loading byte codes through
the ilu connection is just more fancy and interesting.  (Yes, I could
imagine examples where it would provide more functionality then a byte 
code server...)

Even this example which loads the behaviour through ilu, at the end
access the behaviour from a jar file and not from the running vm.

This needs Java jdk-1.1 !  (It uses new java features from the 1.1 release)



The setup is somewhat involved because you need to make sure that
on the client side the FooWhizBangFuzzler class is NOT available
for proof that it really has been loaded through ilu.

stubbing (included in Imakefile)
java-stubber  -custom javaSerialObjects.map -prefix1 javaSerialObjects xerox javaSerialObjects.isl testJavaSerialObjects.isl


compile generated stubs available for both client and server (included in Imakefile)
javac -d classes -classpath ./classes:$ILUHOME/lib/ilu.jar:$JAVAHOME/lib/classes.zip  `cat jstubber.files`

compile written code available for both client and server (included in Imakefile)
javac -d classes -classpath ./classes:$ILUHOME/lib/ilu.jar:$JAVAHOME/lib/classes.zip  Holder.java JavaObjectHandler.java TestReceiving.java ClassAccessorImpl.java 

compile written code which should NOT be available to the client (included in Imakefile)
mkdir specialclasses
javac -d specialclasses -classpath ./specialclasses:./classes:$ILUHOME/lib/ilu.jar:$JAVAHOME/lib/classes.zip TestSending.java FooWhizBangFuzzler.java

Create a jar file to make this stuff available to the "server" as bytes (NOT included in Imakefile)
cd specialclasses; jar cv0f ../MyJarFile.jar *; cd ..

Run the server side with access to the specialclasses (NOT included in Imakefile)
java -classpath ./specialclasses:./classes:$ILUHOME/lib/ilu.jar:$JAVAHOME/lib/classes.zip somepackage.TestSending

Run the client side (NOT included in Imakefile)
java -classpath ./classes:$ILUHOME/lib/ilu.jar:$JAVAHOME/lib/classes.zip otherpackage.TestReceiving
 


================================================================
About custom mapping

Full custom mapping is the ability to externally specify how an isl type
shall be mapped to java.  

It is similar to custom records and custom objects, however there is no
requirement for the custom mapped type to be a subtype of the regular
mapping.  

There is the restriction that custom mapping works
only java object types; that means, the regular mapping of the ilu 
type needs to map into a java object type, as well as the custom
mapped type must be a java object type.  


Full custom mapping is used solely in one
address space; communication ilu processes might not know about whether
or how an ilu type is mapped in the other address space.

All stubs in one address space however must agree on the mapping of
any ilu type.

Custom mapping is implemented using stubber options, however there
needs to be runtime code which handles the conversion from and to
the regular mapped object.


Stubbing requirements

When stubbing the custom mapping needs to be specified with an
commandline option
	-custom description-file-name

We are using a file to dscribe the custom mapping because the actual description 
too cumberson for command line options and must be 
set identical for all stubs accessing a custom mapped type.  

The description file is a list of lines. Each line is either
a comment, or, a custom mapping description for one type.
Custom mapping description have five fields separated with white space.
  
  1) The name of the isl interface (which contains the isl type)
  2) The name of the isl type to be custom mapped
  3) The java class used to map the isl type into
  4) The java class which is used for holders  
  5) If present:  The name of a java class which will be loaded by the stub; this is the class which is expected to implement the transformations between wire type and custom type.

Runtime features

Tha java interface xerox.ilu.IluCustomMapping describes the functions
necessary to implement the custom mapping.  

An  xerox.ilu.IluCustomMapping object must be registered with the helper class
for the regularly mapped type using the static  "_registerCustomMapping"   
method.


Custom mapped type and subclassing do interact whith each other:
Custom mapping works with what ilu calls static types.
  -When you receive a subclass of the static ilu-type; that subclass info gets lost
  -Because of syntax checking you can not transmit a subclass of the static ilu-type, 
     unless it also is a subclass  of the java class.  However
     in that case that case subclass'ness gets lost.
  -when the static class of an argument is a superclass of something with custom mapping
     -when receiveit: customness is lost and you receive the super class
     -when transmit:  syntax checking will not allow this unless 
     custom class is also subclass of static class.  (That case is already defined above:  subclass'ness gets lost)

