README for the "javaserial" example directory.
$Id: README,v 1.8 1997/10/02 23:19:39 jacobi Exp $

[ Copyright (c) 1997 Xerox Corporation.  All Rights Reserved.  

  Unlimited use, reproduction, and distribution of this software is
  permitted.  Any copy of this software must include both the above
  copyright notice of Xerox Corporation and this paragraph.  Any
  distribution of this software 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. ]


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.

USING IMAKE DOESN'T TEST TRANSMITTING BYTE CODE FOR CODE
BUT ONLY TRANSMITTING SERIALIZED STATE.

stubbing
java-stubber  -custom javaSerialObjects.map -prefix1 javaSerialObjects xerox javaSerialObjects.isl testJavaSerialObjects.isl

compile the stubs available for both client and server
javac -d classes `cat jstubber.files`

compile the stuff available for both client and server
javac -d classes Holder.java JavaObjectHandler.java TestReceiving.java ClassAccessorImpl.java 

compile the stuff which should NOT be available to the client
mkdir specialclasses
javac -d specialclasses TestSending.java FooWhizBangFuzzler.java

Create a jar file to make this stuff available to the "server" as bytes
cd specialclasses; jar cv0f ../MyJarFile.jar *; cd ..

Run the server side with access to the specialclasses
env CLASSPATH=specialclasses:$CLASSPATH java somepackage.TestSending 

Run the client side
java 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)

