Go to the previous, next section.

# Using ILU with Java

## Introduction

This document is for the Java programmer who wishes to use ILU. The following sections will show how ILU is mapped into Java constructs and how both Java clients and servers are programmed. See also `ftp://ftp.parc.xerox.com/pub/ilu/misc/ilu4java.html`

### ILU and CORBA

ILU for Java is mostly CORBA compatible.

By this we mean the normal definition of compatibility of english language or of computer science. (In particular we don't use any other organizations definition of "compatible"):

Ilu's compatibility requires the programmers help: Not all programs will be compatible, but it is possible to write compatible programs.

1) Ilu can interoperate with other corba compatible orbs.

2) Applications which are written to use only corba compatible features can switch between ilu and other orbs without changing source code.

ILU for Java's compatibility is not complete or perfect. Not all CORBA orb functions are implemented (DII etc). Ilu implements a subset of the CORBA functionality (for any version), as well as plugs itself into an abstract ORB support interface (if you have a compatible orb, e.g. jdk 1.2 comes with orb delegation packages which ARE compatible).

Ilu generated stubs are not implementing all internal functionality required by other orbs. Stubs generated by other orbs do not provide all internal functionality required by Ilu. This is normally not a problem for any application; should there be a problem, the Ilu stubber has a -prefix option to generate stubs into a different package.

javasoft's interpretation of the standard mapping: (may or may not be accurate): `http://java.sun.com/products/jdk/idl/docs/idl-java.html`

The standard mapping is available from OMG as PDF document: `ftp://ftp.omg.org/pub/docs/orbos/97-03-01.pdf` or a newer version `ftp://www.omg.org/pub/docs/formal/98-02-29.pdf`

## The ISL Mapping to Java

The mapping is similar to the corba mapping. Applications programmers should not notice a difference whether their application use corba stubs or ILU stubs, as long as the application stays withing the corba subset. Many ilu types however implement the java.io.Serializable interface.

### Names

In general ISL names are mapped to Java names and identifiers with no change.

If a name collision could be generated in the mapped Java code, the name collision is resolved by prepending an underscore (_) to the mapped name.

This mapping, matches the CORBA standard. ILU considers all use of java reserved words, as well as method names of class java.lang.Object to be colliding.

Furthermore, names which have prefixes or postfixes which COULD match identifiers otherwise generated by ILU are considered colliding. (Like "Helper", "Holder")

### Interfaces

An ISL `interface` is mapped to a Java package with the same name. For details see the CORBA standard for modules.

Avoid IDL features which are not in the scope of a idl module (= ISL Interface).

The ISL directive (DIRECTIVE-EXPERIMENTAL) options have a few special keys for the java stubber.

Directives which starts with "JAVA-PREFIX" contains a quoted string which is used as a package prefix. This can also be achieved with a stubber command line -prefix option.

Directives which starts with "JAVA-CUSTOMFILE" contains a quoted string which is used as a file name describing custom mapping. This can also be achieved with a stubber command line -custom option.

Directives which starts with "JAVA-REMOTE" contains a list of quoted string which are names of ilu object types (or "*"). Those object types will extend java.rmi.Remote and all methods will declare to throw java.rmi.RemoteException. However, if you combine RMI remotes and ilu objects, you need to know what you are doing or you'll be surprized. (This automaticly implies "JAVA-NOCORBAOBJECT")

Directives which starts with "JAVA-NOCORBAOBJECT" contains a list of quoted string which are names of ilu object types (or "*"). Those object types will NOT extend org.omg.CORBA.Object. Don't use corba specific methods on those (You'd get a type error).

### Basic Types

BOOLEAN is mapped in to java boolean.

BYTE is mapped int java byte. ILU carries the bit pattern, not the numerical value.

CHAR and SHORT CHAR are mapped int java char. Values outside their range throw an exception when marshalling.

SHORT INTEGER, SHORT CARDINAL maps into java short.

INTEGER, CARDINAL map into java int.

LONG INTEGER, LONG CARDINAL map into java long.

The unsigned integer types map as bit pattern.

SHORT REAL maps into java float.

REAL maps into java double.

128 bit floating point values are carried around as "xerox.ilu.types.float128" but no operations are available.

The "new" extended IDL types fixed is not yet supported.

This mapping matches the standard corba mapping.

#### Constant

See the corba standard.

### Strings

See the corba standard.

### Pickles and Typecodes

See the corba standard for ANY and Typecodes.

At the currenbt time not yet implementing java.io.Serializable

### Constructed Types

#### About Java Object serialization

All (*) Constructed Types are mapped into java types which implement java.io.Serializable. Whether the type realy is serializable depends on whether its element type is. Serialization of a constructed type whose element type is not serializable throws an exception.

(*) Two exceptions: Custom surrogates are only serializable if the surrogate type specified so.

Likewise, true object type implementations are only serializable if the implementing class specified so. The implementing class does NOT need to implement any methods, but it needs to implement java.io.Serializable

#### Enumeration

See the corba standard.

Serialization in an ILU context works as expected. In PRE-JDK1.2 however, serialization in a non-ILU context might loose the object identity. (Otherwise equal elements can be detected with "==")

#### Array

Mapped into a java array of the mapped element type. See the corba standard.

#### Sequence

Mapped into a java array of the mapped element type. See the corba standard.

#### Record

See the corba standard.

#### Union

See the corba standard.

#### Optional

ISL Optionals have no corresponding corba type. If the base type of the optional maps into a Java primitive type we will represent the optional with the corresponding Java wrapper or container class. (Boolean, Character, Double, Float, Integer, Short, Byte, or Long). The null value represents absence of the parameter.

If the base type of the optional maps into a Java object type, the optional is mapped as if it weren't optional. The null value represents absence of the parameter.

In the case of Java Strings the difference between a null String and an empty string serves this distinction perfectly.

### Object Types

See the CORBA standard for "corba interfaces".

#### Surrogate and True Object Types

To request creation of an object the ``createTrueObject`` method is called. The implementation of ``createTrueObject`` is expected to call ``super.returnTrueObject`` to register the created object.

True object have to implement all the interfaces required by their type and by type org.omg.CORBA.Object (unless the Ilu type explicitely doesn't extend org.omg.CORBA.Object)

Unlinke, CORBA, this is all which is absolutely necessary. However, unless there is a need to do otherwise we strongly recommend extending the base class xerox.ilu.IluObjectBase. This will take care automatically of a long list of problems (See the section about garbage collection). But, if you can't use one of those base classes, in ilu you do have alternatives.

If you can't extend a predefined base class, you can make a class of your own and implement the necessary interface. With the ilu distribution is a "template" ObjectImpl.template which cut be pasted into your own source code to do so automatically. See the ObjectImpl.template file in the runtime/java directory.

#### Methods, Parameters, and Exceptions

#### Java Garbage Collection, Distributed Garbage Collection, and/or COLLECTIBLE

The Garbage Collection features in Ilu look much more difficult then they are. The difficulties arise in supporting various important cases in wild combinations. Most likely your application will not use the whole span of complexities but simply chooses one of the cases.

For Ilu COLLECTIBLE objects (see generic Ilu documentation) do not hang onto objects longer then you need. That is true for both surrogate and true objects.

Non COLLECTIBLE objects are alive until deleted. If you are providing a true object implemementation, it is your responsibility to prevent this object from being garbage collected; Ilu does not necessarily do so. If the program lets a true object being garbage collected that means Ilu will eventually stop serving it.

There are several means to have Ilu help keeping an object alive:

If possible, true objects should extend IluObjectBase (or use the template). This would take care of all the complexities following.

Most direct, the xerox.Ilu.registerTrueObject method provides a lifetime argument. This should be a lifetime value as is provided by the xerox.ilu.IluLifetimeArgs class. However since many registrations happen implicitely or in places which do not provide that argument there are other means to specify lifetime.

There are two marker interfaces xerox.Ilu.IluLifetimeForget and xerox.Ilu.IluLifetimeRemember which can be implemented by true objects. Doing so guides Ilu's behaviour if xerox.Ilu.registerTrueObject does not specify an explicit method or xerox.Ilu.registerTrueObject is not explicitely used at all.

Of course the application could simply manage the lifetime itself, but see the note below.

Note that there is a big difference in whether a true object is extending IluObjectBase or not. Ilu goes to tremedous troubles to not require applications to extend a predefined base class. However if this service is not needed we recommend applications to simply extend IluObjectBase for true object types. By doing so, Ilu can take advantage of inherited code which helps it handle lifetime. If Ilu can finds no hint at all that the application is doing something about the lifetime, Ilu's behaviour might become more conservative then the programmer likes. (For CORBA users: using org.omg.CORBA.portable.ObjectImpl.java works as well as xerox.ilu.IluObjectBase, but you can only do corba things with it. Use xerox.ilu.IluObjectBase otherwise.)

Note to the curious why the internal complexity is necessary: Ilu is implementing weak refs, even on jdk version which have no support for it.

ILU Java reads the `ILU_COLLECTABLE_CINFO` environment variable for setting up ports for the special object used to guide collectible objecs.

#### Java serialization

Surrogates implement java.io.Serializable. We recommend to our implementors to make true object types serializable as well. The IluObjectBase interface does so.

### How to make your idl Java friendly

Note that you don't have to do this. Ilu will mangle your names if necessary.

However, if you keep your names Java friendly, your stubs will be easier to read and debug by people used to popular java coding standards or the CORBA standard mapping. If you avoid name conflicts no esoteric name mangling needs to happen and your ilu stubs are more likely to match the CORBA standard correctly.

1. Avoid Java keywords. (e.g. boolean, int, class, for, ...)
2. Avoid names of Java standard classes (in the java.lang package). (e.g. String, Integer, RuntimeException)
3. Avoid suffixes which are used by CORBA standard for your type and class names. (e.g. Stubs, Operations, Helper, Holder, ImplBase)
4. Avoid prefixes which are used by CORBA standard for your type and class names. (e.g. POA_)
5. Avoid suffixes which are generated by ILU for your type and class names. (e.g. _exh_)
6. Avoid gratuidous typedefs. (But it is ok to use typedefs for functional reasons)
7. Avoid using the same name for the interface and a type.
8. As a courtesy, try to also avoid names which cause problems for other programming languages.
9. Start your types, classes and exceptions with capital letters.
10. Start your methods and enumeration values with small letters

## Access to standard ILU features

### Servers and Ports

#### True Servers

Each object exported by an implementation must belong to a true server, an instance of the Java type `IluServer` which is implemented by the ``xerox.ilu.IluServer`` class.

An `IluServer` instance can be created by calling the function ``ilu.createServer([serverID])``, which returns a value of type `IluServer`. If serverID is a string, it specifies the server ID; if it is the Java value `None`, a server ID will be invented automatically.

Other methods allow the specification of a daemon flags or ports for different transports or protocols, or an object table, which allows specification of a callback function for creating true instances on demand.

The first time a true server is created, it becomes the default server. The default server is used for an exported object if a server is not otherwise specified or when it is explicitly requested with the ``defaultServer`` method. If an object is exported before any servers have been created, one will be created automatically using default parameters and possibly a message to that effect will be written to ``System.err``.

An object of type ``IluServer`` has an accessor method ``serverId()`` that returns its server ID.

Look at the Java classes IluServer and IluPort for details. In general servers may be omitted and a default server is used. IluPort as well may be ommited.

ILU for Java reads the `ILU_DEFAULT_CINFO` environment variable for setting up default ports.

See the section Java Garbage Collection, Distributed Garbage Collection, and/or COLLECTIBLE for how to setting up the port used for implementing COLLECTIBLE objects.

#### Object Tables

Object tables are defined in the class IluObjectTable. To define an object table one subclasses ``IluObjectTable`` and attached the subclasses to an ``IluServer`` when the server is created. An ``IluObjectTable`` can only be attched to one ``IluServer``.

Because the Object Tables calls are made with internal ILU locks held, it must not do recursive calls into ILU.

### Threading and Event Loops

ILU uses Java threads. There is no event loop option.

It is possible to change thread priorities by setting properties at start up of the application. This is however not recommended.

A few arguments can be passed by setting "properties" on the thread. This is motivated by the java standard mapping which has no place to pass extra arguments.

However Java threads, if not subclassed do not support "properties". To set thread properties, calls need be performed from an xerox.ilu.IluServiceThread

### Custom Records

Record types are mapped to Java objects. It is possible provide a subclass which will be used by ILU instead.

"Custom Records" class assign their own class to a (protected) java.lang.Class variable (_theClass) of the original stub class for the record. Whenever ILU needs to allocate an instance of such a record it will allocate a an instance of the subclass instead.

### Custom Surrogates

Surrogate creation can be intercepted. To do so one registers either a Java class, or, a factory object with the stub class implementing an object type. See the methods ``IluClassRep.setSurrClass`` or ``IluClassRep.setSurrFactory`` for details.

### String Binding Handle Formation

The class ``xerox.ilu.IluSBH`` provides methods for both scanning and composing string binding handles.

### Simple Binding

An object may be published using the simple binding service by calling the method
``xerox.ilu.IluSimpleBinding.publish()``.

An object may be unpublished by calling the method `xerox.ilu.IluSimpleBinding.withdraw()`.

A published ILU object may be obtained by calling ``xerox.ilu.IluSimpleBinding.lookup(sid, ih, cl)``, where sid is object's server's server ID, ih is the object's instance handle, and cl is its ILU class. The ILU class for a type TYPE may be obtained in Java by calling `TYPEStub.iluClass()`.

As alternative to IluSimpleBinding, the ``resolve_initial_references`` method from org.omg.CORBA.ORB could be used. See another alternative in the chapter about CosNaming.

### Principal Identities and Passports

Passport are represented in the class `IluPassport`. Identities are represented by the class `IluIdentity`. The class `IluIdentityType` represents the type of an identity. A passport can carry at most one IluIdentity of each `IluIdentityType`.

Client generated passports are mutable and stay alive until garbage collected. Clients tell ILU about their passports via the current thread which must be a subclass of IluServiceThread. The methods `IluServiceThread.setMyStubPassport` and `IluServiceThread.setStubPassport` can be used to set passports. For security reasons passports of other threads can not be set. (We need to rethink the possible threats). However it is possible to clear the passport of any thread (as this is only a denial of service attack).

ILU generated passports are immutable and can be used only while the call for which it has been constructed is ongoing. If used afterwards, an exception will be raised. For a client to access an Ilu generated passports, the method `IluPassport.getSkeletonPassport` is used.

These passport features are carried around fully, but since the api to create identities and identity type features are still missing, usefullness of passports is grossly limited.

## Building ILU-for-Java Applications

### Stub Generation

Please don't confuse the java stubber (called javah) with the ilu stubber (called java-stubber). javah is used to create native method interfaces. java-stubber is named that way to provide a naming scheme matching other ilu stubbers for other programing languages.

To generate Java stubs from an ISL file, use the program `java-stubber`. Since the stubber creates a surprisingly large number of Java files, these files must be directed to a designated stub directory.

Using a designated stub directory is only a default and could be changed. We strongly advice against changing this to protect your manually written source files from being overwritten.

To be able to compile the huge list of files, the stubber generates a file with a list of generated Java files is generated.

The stubber recognizes the following options or switches:

- -dir DIRECTORY PATH
  The stubs are generated into the directory specified by the DIRECTORY PATH argument. This command line option could direct the stubs into the working directory, but if omitted the default path is ``./javastubs'`.
- -xrx
  The old Xerox PARC Java/ILU mapping is used for this interface. (See also -omg.) The main difference between -xrx and -omg option are the holder classes; we are working on eliminating this difference.
- -omg
  More or less what we imagine is OMG's mapping for this interface is used. Remember that this is about the interface to the application, not about the interface to the orb.
- -flat
  Generate all stubs into the designated stub directory directly. This is not recommended because files can be overwritten. The default behavior is to write stubs in subdirectories according to their interface names.
- -prefix PACKAGE_PREFIX
  Generates stubs into a package prefixed with the named PACKAGE_PREFIX.
- -noprefix
  Generates stubs without package prefix. Recommended for serious interfaces; NOT recommended for experimenting.
- -noserv
  Generates stubs which save a few bytes but can't be used on the true side. NOT recommended.
- -reportfile REPORT-FILENAME
  Additional parameter for a file name. A list of generated Java files is generated. This list can be used to make makefiles, etc. -reportfile has no `suffix' version (see below).
- -noreport
  The list of generated Java files is not generated. -noreport has no `suffix' version (see below).
- -exsuffix
  Define a suffix used in the name of exceptions. NOT recommended.

All command line options (unless if documented otherwise) have a second variant with a suffix "1". If the command line option with suffix is used, an extra argument for the name of an interface is read, and the option only affects that interface. The un-suffixed command line options affect all interfaces. Suffixed command line options override un-suffixed command line options. Option processing is from left to right.

The stubber can be run without arguments to generate a usage message.

#### Problems and Solutions

- Stubbing will create a very large number of files with the Java extension. You don't want to loose your source files among the generated stubs.
  We recommend creating a subdirectory called ``./javastubs/'`. All generated stubs should be generated into this directory. (This is the default; we do not recommend changes.) (As a safety measure) if a non-standard directory is used, the stubber does NOT create it automatically. Unlike the top level stub directory, sub directories are created automatically by the stubber.
- Stubs might have conflicting names.
  Generate stubs in a hierarchical directory structure, according to their Java package structure. (This is the default; we do not recommend changes.)
- Stubs might conflict with manually generated Java sources.
  1. Use good ILU interface names (Or OMG IDL module names). This is recommended for "production" ILU use.
  2. Direct the stubber to generate all stubs into a prefix package stubs. This is recommended for perusing non-well-known interfaces. Use the -prefix option to name a prefix.
  3. Stubs conflict with standard stubs loaded with the bootclass path. Use the -prefix option when stubbing.

#### Java Compilation

Unless you are using make files, we recommend stubbing into empty directories. This allows the Java compiler to compile all Java files with an asterisk syntax. Always use the -d option with the Java compiler!!!

In unix, the report file can be used to generate the list of files to be compiled. It can be used directly with a back-quote cat report-file back-quote syntax.

#### Execution

At execution time the loader needs to find

1. Your application and its regular imports (binaries; resp. classes). This is normal Java usage. It might be easiest to the `CLASSPATH` environment variable.
2. Java binaries (classes) from generated stubs. There is nothing special here. Compile the stubs into whatever directory you want (e.g. ``./classes/'`) and put that directory on the `CLASSPATH` environment variable.
3. Java binaries (classes) from ILU runtime support. The classes binaries from the ILU runtime support are compiled into the jar file ``ILUHOME/lib/ilu.jar'`; put this file on your `CLASSPATH` environment variable. Also put the jar file ``ILUHOME/lib/ilujavaobv.jar'` on your `CLASSPATH` environment variable if you use Java objects by value or Java marshalled objects.

   (Ilu's files from the org.omg class conflict with corresponding implementations deliverd by Sun microsystems. Ilu run's with either versions, your choice in jdk1.1. However in jdk1.2, because of Sun's version are bootclasses, replacing them might be difficult.)

   Java JDK 1.1.4 starts to garbage collect classes. There was a known bug in JDK about collection of classes (fixed in jdk1.1.6). ILU depends on its classes not being garbage collected and has some strange code to prevent such collection even in case of the buggy jdk's. Nevertheless it might be conservative to use the -noclassgc switch with jdk1.1.4 and jdk 1.1.5.

   If your java system does not support jar files, the classes are compiled into ``ILUHOME/lib/classes/'`.

4. C binaries (object files) from ILU runtime support and kernel. The C binaries (object files) are accessed using the `LD_LIBRARY_PATH`. The path must have an entry pointing into the ILU Java runtime directory.

#### Debugging

Use of the standard ILU debugging environment variable `ILU_DEBUG` is recommended; please section Debugging ILU Programs.

Java ILU listens to a large number of Java command line switches. The simplest one is to set the -D command line option (e.g. -Dilu.debug=4). For more specialized command line switches look at the ``xerox.ilu.IluDebug.java`` file. Looking at the well documented source code is more relieble then duplicating the rather fast changing flags in the documentation.

Note that the -D option of the Java interpreter has no relationship whatsoever to the -d option of the Java compiler.

When using `dbx` or `gdb`: The standard Java binaries (classes) are found automaticly (without specification on the `CLASSPATH` environment variable) when not debugging. When debugging, those classes must be specified on the `CLASSPATH`. We don't understand this difference.

#### Debugging native ILU code

When setting break points with dbx or gdb it is necessary to make ilu wait first. Ilu supports the -Dilu.interactivewait=true property to add an extra interactive wait. For details look at the class xerox.ilu.IluInit2.

### Implementing an ILU module in Java

A Java program which wants to implement a object type T from interface `I` needs to create a class which implements the stubber-generated Java interface `I` and java class org.omg.Object (Preferably by extending the xerox.ilu.IluObjectBase class). Objects of this class then are made available (registered) with the ILU runtime either implicitly or explicitly, or with an object table.

Explicit registration allows specification of additional parameters, like the string binding handle, the server, and more. Explicit registration done by calling the stubber generated method ``I.T_stub.registerTrueObject()``. As an alternative, if the programmer is willing to specify the class, he can also use the method ``xerox.ilu.Ilu.registerTrueObject`` directly.

Objects are implicitly registered with ILU if they are returned as a result value from a method call that returns an object type or has an object type as an INOUT or OUT parameter or if they are published using the Simple Binding mechanism.

### Hints about implicit registration

If objects are not registered explicitely but get auto-registered on use, there are two pitfalls to watch out for.

1. The ILU type must be unique. If no type is given ILU will look at the Java type and make its best possible guess about the ILU type.
2. The ILU type must be loaded. Unless the ILU type is loaded the registrar will never find that type. If there is any doubt about whether a stub implementing an ILU type is loaded or not, it might be useful to actually load the class. The ilu.load property can be used to load a class from external commands. The stubber also generates a special class whose sole purpose is to help load whatever is necessary for the registrar to not miss a class.

#### Java's single inheritance classes.

If you can not extending the xerox.ilu.IluObjectBase class, there is a template ObjectImpl.template which you can cut and paste into the source code of your own class.

Alternatively you can use what other orbs call the tie approach. Check the stubber options on how to generate tie classes. When using the tie approach you should find a means to give your tie class an appropriate life time.

A client program may obtain a reference to an ILU object in one of the following ways:

1. True instance creation.
   The application may create an true instance of a class.
2. ``objectFromSBH()``
   Knowing the string binding handle sbh and class (`xerox.ilu.IluClassRep`) (or superclass) cl of an object, call ``xerox.ilu.Ilu.objectFromSBH(sbh, cl)`` which returns an instance of that class.

   For example, to obtain an instance of ISL type `square` from `INTERFACE shapes`, which has a string binding handle sbh, one would call ``xerox.ilu.Ilu.objectFromSBH(sbh, shapes.squareStub.iluClass())``.

3. ILU Simple Binding.
   Knowing the object ID (sid, ih) and class cl of an object that has been published using the simple binding service, call ``xerox.ilu.IluSimpleBinding.lookup(sid, ih, cl)`` which returns an instance of that class (or raises an exception if the lookup fails).
4. Return result or parameter.
   An instance may be received as a result value from a method call that returns an object type or has an object type as an `INOUT` or `OUT` parameter.

To get the ilu class (java type `xerox.ilu.Ilu.IluClassRep`), use one of these methods:

1. The static iluClass() method generated with the stub class.
2. The static xerox.ilu.IluClassRep.fromIluObject method with an object instance argument.
3. The xerox.ilu.IluClassRep.fromIluClassName method with the ISL name of the class as argument. For Ilu to find the class it is necessary that the java stub implementing the ISL class has been loaded.

## Notes for ILU for Java in applets

Use of ILU in applets is not impossible, but it is not fully supported either. Read about the problems to see what you can do and what you can't.

The highlevel problem are native code and no support for class unloading.

ILU has native methods. That means Ilu must be loaded somewhere/somehow where native methods are supported. ILU has been loaded into Hotjava, java-plugin (Activator). This can be solved in JDK 1.1 by loading ILU on the classpath, or by using signed applets (which has not been tested).

ILU also has been loaded into the regular Netscape 4.05 VM, but that needs special setup in the Ilu build process. (See Imakefile and source/runtime/java/IluMozillaExtra.java). This has not been tested in the recent release and is depricated in favor of plugin.

In JDK1.2 Ilu can be made an installed extension. (Downloaded extension in JDK1.2 don't yet support native methods, even when signed). If you run Ilu as an extension you also need the stubs in the extension, otherwise the classloader would throw a security exception.

Likewise, if you manage to put Ilu into the bootclasses you also need the stubs in the bootclasses, for the same reason.

To run Ilu as an extenson, out the jar files in the proper extension directory, but don't forget to put the native code into the right place also.

ILU does not support class unloading. ILU itself is quite security aware, but there are still some problems. In particular, there is a security problem if an applet loads malicious stubs and later another applet things these are correct stubs. To prevent class unloading, stubs should be in the same classloader as the ILU runtime: Either both signed and dynamic, or both on the classpath, or, both as an extension.

Very little testing of running ILU in a browser or a java-pluggin has been done. Set up your environment that stub classes will never be unloaded.

## Notes for Java on particular architectures

### Notes for Java on Windows

Please see the "Java" subsection of "Building ILU" in the chapter section Using ILU with Microsoft Windows.

### Notes for Java on Linux

Users of Linux Redhat 5.1 reported problems when Ilu was configured using the "poll" system call. The configuration option --with-java-nopoll can be used to force use of "select" instead "poll".

### Native threads versus green threads

On UNIX systems, Sun's Java runtime exports one or both of two different interfaces to its multi-threading support, depending on which of two implementations is used. The choice is between so-called "green threads", which are "user level" threads entirely implemented in the Java runtime, and "native threads", which use the thread support offered by the OS and/or C runtime.

On Win32 systems, only native threads are available. In case that the ILU for Java system is built with JNI, the difference between "green threads", and "native threads" does not matter.

ILU faces the choice between native and green threads at two times. The first is when ILU is built: ILU can be built for use with either or both kinds of Java threading system. ILU's configuration script (used at ILU build time) tries to figure out which kind(s) of Java threads are available in the local Java implementation and build ILU support for as many kind(s) of Java threads as are available. If it gets this wrong, you can explicitly tell it which kind(s) of threads to build support for, with a configuration option: `--with-java-threads=KINDS`, where KINDS is one of `green`, `native`, or `both`.

The second time when ILU must choose between Java threading systems is at loading time for Java native code library. Sadly we do not know how to determine whether Java is using green threads or native threads. ILU simply tries one version, and, if that throws an exception and another version is available, tries the other version. (The order is important: on a certain Java VM and threading model the wrong native code didn't throw exceptions but caused a crash.)

### JNI versus ONI vesus RNI

Ilu is configured differently according to what native method interface is used by your java VM. Mostly, the configuration step will choose the right system for you.

The choice of RNI is quite obvious: Use RNI on microsoft sdk and nowhere else. (This happens automatically)

The choice of JNI versus ONI is more difficult. In jdk1.1 we recommend using ONI because JNI doesn't implement weak pointers, the java VM's don't do compaction, and, ONI has been used in most testing. In jdk1.2 we recommend using ONI IF your system supports ONI and does NOT use memory compaction. Otherwise we recommend using JNI. The ILU configuartion process chooses automaticly whether to use JNI or ONI. Should this choice be wrong, it can be overridden with the `--with-java-jni` option.

### Java releases

The ilu build builds one version of binary ilu. However, the filenames for the binaries are distinct. It is possible to do one ilu build for jdk1.1 and one ilu build for jdk1.2... each in the same directory. This works because the by accident or design, the java classes for jdk 1.1 and jdk1.2 are compatible. Ilu at runtime decides which version of the native libraries to load.

Ilu used to work with various jdk1.2beta releases but after usage of jdk1.2 Ilu went through major changes in the configuration and beta releases have thereafter never been tested anymore.

## CosNaming

Sadly, Ilu stubs and standard stubs are not interchangable. In Java jdk1.2 the org.omg.CosNaming stubs are in the Java core and Ilu has no chance of substituting its own stubs. There are two possible ways to handle this problem:

a) This is for people who want to use Ilu strictly corba compatible. Stub the CosNaming.idl with the standard org.omg prefix. Load a version of java which does not have CosNaming from another source. If an application can do this its use of CosNaming is corba compatible in source code. (It is always corba compatible on the wire).

b) If your application can not replace the standard CosNaming packages. Stub the CosNaming.idl with another prefix, for example xorg.omg. The stubs will have a different package name, but they will be corba compatible on the wire.

We recommend using CosNaming.idl from ilu's etc/CosNaming directory. The reason for this is that the idl does not have a package prefix in the module name but only as a pragma. So whatever prefix is generated when stubbing CosNaming.idl, the names used on the wire get picked from the pragma and your CosNaming stubs look right on the wire.

### CosNaming Naming Server

Should you use ILU's CosNaming Naming Server? It really doesn't matter. The service is wire compatible and accessed via your stubs. Ilu's service and somebody elses service are interchangeable.

### Bootstrapping with CosNaming

It is possible to start up Ilu like a regular orb and bootstrap via the CosNaming service. There is an example in the chapter about the ORB class. See also `ftp://ftp.parc.xerox.com/pub/ilu/misc/iluSunJavaIDL.html`

You will need to specify that ILU is used as the ORB. To do this use a property like this: -Dorg.omg.CORBA.ORBClass=xerox.ilu.IluORB.

You will need to force your application to load the required stubs. use a property like this: -Dilu.load=xorg.omg.CosNaming._allJavaStubs:HelloApp._allJavaStubs This usage demonstrates loading both, the stubs from CosNaming as well as the stubs from the application.

You will need to tell ILU what the string binding handle of the root context of the naming service is. One way is to copy the IOR from when the naming service was started, as a propert like this: -DNameService=IOR:000000000000002849444c3a6f6d672e6f72672f436f734e616d696e672f4e616d696e67436f6e746578743a312e3000000000010000000000000044000100000000001b7275626265726475636b792e706172632e7865726f782e636f6d000080ac000000000018afabcafe00000002446942fc000000080000000000000000

The other way is to write the IOR into a file or an URL. In unix this could even be done by redirecting the output when starting the naming service. Use a property like this to read the IOR from a file: -DNameService=file:/tmp/file.temp or like this to read a URL: -DNameService=url:http://x.y.com/foo.htm

You might use the xerox.ilu.IluORB.resolve_initial_sbh or xerox.ilu.IluORB.readSBHFromURL methods directly to make up your own way of bootstrapping Ilu.

## ILU for Java Reference

The interface is rather large. This section will cover the most important classes but reading the standard javadoc documentation or reading the source will be more complete.

### javadoc documentation

ILU java code contains javadoc tags. We think however that reading the source code might be easier then reading the javadoc output.

javadoc documentation: `http://java.sun.com/products/jdk/javadoc/index.html`

The ILU build does not automaticaly generate the javadoc documentation.

#### Build of the javadoc documentation

The ILU build does not automaticaly generate the javadoc documentation.

With jdk1.1 you need to manually create an images subdirectory and copy the images. (This has been fixed in jdk1.2). Since I don't know how to make the ilu build find the images, the build does not do the javadoc step automatically.

Another reason to not automatically build the javadoc documentation is that different users might want to or not include -package and -private features. The third reason for manual build is that some users might want to include standard packages into the same documentation build. For some java release the way to make javadoc comments is this:

    # create a javadocs directory
    # we recommend using ILUHOME/doc/javadocs
    # (When making links, they might point to that directory)
    mkdir javadocs

    # Go to the java sources
    cd ILUSRC/runtime/java/jsrc

    # build the javadoc documentation into the javadocs directory
    javadoc -d javadocs xerox.basics xerox.ilu xerox.ilu.tools org.omg.CORBA org.omg.CORBA.portable org.omg.PortableServer

    # copy the javadoc images into the proper place (not necessary with jdk-1.2)
    # (Substitute the source as you most likely have the images somewhere else...)
    cd javadocs; mkdir images; cd images; cp /project/java/jdk-1.1/docs/api/images/* .

The java runtime source directory contains a script "buildjavadoc" which could be used to create javadoc documentation using JDK1.2

### Description of Java classes

#### CORBA Exceptions

Ilu has its own version of CORBA Exceptions, or, uses the CORBA Exceptions coming with the standard distribution. This is a configuration choice.

1. org.omg.CORBA.UserException This is the base class for all generated user exceptions.
2. org.omg.CORBA.SystemException This is the base class for all system exceptions.

1. org.omg.CORBA.BAD_CONTEXT
2. org.omg.CORBA.BAD_INV_ORDER
3. org.omg.CORBA.BAD_OPERATION
4. org.omg.CORBA.BAD_PARAM
5. org.omg.CORBA.BAD_TYPECODE
6. org.omg.CORBA.COMM_FAILURE
7. org.omg.CORBA.DATA_CONVERSION
8. org.omg.CORBA.FREE_MEM
9. org.omg.CORBA.IMP_LIMIT
10. org.omg.CORBA.INITIALIZE
11. org.omg.CORBA.INTERNAL
12. org.omg.CORBA.INTF_REPOS
13. org.omg.CORBA.INV_FLAG
14. org.omg.CORBA.INV_IDENT
15. org.omg.CORBA.INV_OBJREF
16. org.omg.CORBA.MARSHAL
17. org.omg.CORBA.NO_IMPLEMENT
18. org.omg.CORBA.NO_MEMORY
19. org.omg.CORBA.NO_PERMISSION
20. org.omg.CORBA.NO_RESOURCES
21. org.omg.CORBA.NO_RESPONSE
22. org.omg.CORBA.OBJ_ADAPTER
23. org.omg.CORBA.OBJECT_NOT_EXIST
24. org.omg.CORBA.PERSIST_STORE
25. org.omg.CORBA.TRANSACTIONREQUIRED
26. org.omg.CORBA.TRANSACTIONROLLEDBACK
27. org.omg.CORBA.TRANSIENT
28. org.omg.CORBA.UNKNOWN

#### Holder classes

A means to pass a CORBA things as a reference parameter. Holder classes are mutable.

Ilu has its own version of Holder classes, or, uses the CORBA Holder classes coming with the standard distribution. This is a configuration choice.

1. org.omg.CORBA.AnyHolder
2. org.omg.CORBA.BooleanHolder
3. org.omg.CORBA.ByteHolder
4. org.omg.CORBA.CharHolder
5. org.omg.CORBA.DoubleHolder
6. org.omg.CORBA.FloatHolder
7. org.omg.CORBA.IntHolder
8. org.omg.CORBA.LongHolder
9. org.omg.CORBA.ObjectHolder
10. org.omg.CORBA.PrincipalHolder
11. org.omg.CORBA.ShortHolder
12. org.omg.CORBA.StringHolder
13. org.omg.CORBA.TypeCodeHolder

#### CORBA classes

Ilu has its own version of CORBA classes, or, uses the CORBA classes coming with the standard distribution. This is a configuration choice.

Some of Ilu's own version of corba classes do not completely correspond to the standard. The intend is that a the corba classes look and work like the standard classes as seen by client applications SOURCE code.

1. org.omg.CORBA.Any A skeleton class to achieve corba source compatibility

2. org.omg.CORBA.BOA There is no use for this in Ilu. This type is provided to make corba compatible calls...

3. org.omg.CORBA.CompletionStatus

4. org.omg.CORBA.CORBA_ObjectHelper The helper class for CORBA::Object

5. org.omg.CORBA.CORBA_ObjectStub For the implementation of CORBA::Object

6. org.omg.CORBA.portable.ObjectImpl CORBA (but not ilu) requires all true classes to inherit from this class.

7. org.omg.CORBA.Object CORBA::Object. (WARNING While all ilu objects have implement the java interface org.omg.CORBA.Object, that doesn't mean the corresponding ISL or IDL type is a subclass of CORBA::Object! Use runtime typing)

8. org.omg.CORBA.ORB Makes Ilu look like it would be a CORBA ORB

   The way ``resolve_initial_references`` works:

   The argument is used as a key to access the ORB properties. (The ORB properties can be set either with init, or if not set default to the java system properties and, in case of applications it might read environment variables). The property is accessed; its value is supposed to be an ilu SBH. The object for this SBH is accessed and returned by resolve_initial_references.

   There is an extra twist: If the SBH string starts with "file:" that adds an extra level of indirection: Ilu will access the file and use the contents of the first line as the SBH instead. (And even better: If the first line looks like a re-direct from Sun's Java IDL naming service, ilu will read the second line...)

   A typical start up using this feature coold look like this:

       org.omg.CORBA.ORB orb = ...
       org.omg.CORBA.Object objRef =
            orb.resolve_initial_references("NameService");
       org.omg.CosNaming.NamingContext ncRef = NamingContextHelper.narrow(objRef);

   When starting the application, the property can be set on the command line, for example:

   java -Dorg.omg.CORBA.ORBClass=xerox.ilu.IluORB -Dilu.load=org.omg.CosNaming._allJavaStubs:MyApplication._allJavaStubs -DNameService=IOR:000000000000002849444C3A6F6D672E6F72672F436F734E616D696E672F4E616D696E67436F6E746578743A312E300000000001494C55000000009A0001000000000092696C753A31332E322E3131362E33322E336461342E33343663396337302E312F31332E322E3131362E33322E336461342E33343663396337302E303B49444C2533416F6D672E6F7267253246436F734E616D696E672532464E616D696E67436F6E74657874253341312E303B73756E7270634073756E727063726D3D7463705F31332E322E3131362E33325F333439373700 startMyApplication

   or maybe

   java -Dorg.omg.CORBA.ORBClass=xerox.ilu.IluORB -Dilu.load=org.omg.CosNaming._allJavaStubs:MyApplication._allJavaStubs -DNameService=file:/tilde/yourName/fileName startMyApplication

   The above example loads the CosNaming stubs from the command line. The reason for this is to make sure that the stubs are actually loaded before orb.resolve_initial_references is called. Ilu requires types to be known (stubs loaded) before an object of that type is read, otherwise the type information will be lost.

   Warning: In jdk1.2 the CosNaming stubs are in the java core and not replaceable by Ilu. This example works only jdk1.1 based, or in jdk1.2 when fooling with the boot class path. In regular jdk1.2 use we recommend changing the package prefix for the CosNaming stubs, maybe use xorg.omg instead org.omg (therefore also update the application and the -Dilu.load properties).

9. org.omg.CORBA.TypeCode

10. org.omg.CORBA.TCKind

#### Basic environment classes

These classes are public, but not necessarily considered part of ilu.

1. xerox.basics.Consumer0 A simple queue with a thread which consumes all elements provided. Class is public; used by ilu but not part of the ilu public api.

2. xerox.basics.Environment A simple means to access or specify the environment. Class is public; used by ilu but not part of the ilu public api.

   The command line flag interface to load additional classes looks usefull to ilu, but MUST NOT be used from ilu client applications directly. Ilu duplicates this functionality with an ilu.load property. The difference is the initialization order! The ilu.load property avoids bad initialization order loops.

3. xerox.basics.IntTab An IntTab is a hash table which associates int keys with objects.

4. xerox.basics.IntTabEnumerator For enumerating IntTab values

5. xerox.basics.Queue A simple queue class.

6. xerox.basics.NowhereStream A trivial OutputStream class

7. xerox.basics.NowhereWriter A trivial Writer class

8. xerox.basics.VMExtras

   Remembers objects; better then using static variables as VMExtras also deals with collecting classes.

   High priority thread introducing proper timeslicing into the Java vm.

#### ILU exceptions

1. org.omg.CORBA.SystemException
2. org.omg.CORBA.UserException

1. xerox.ilu.IluRuntimeException IluRuntimeException is super class of all IluRuntimeExceptions. RuntimeException's don't need catch phrases.

2. xerox.ilu.IluCustomMappingException

3. xerox.ilu.IluInconsistentCallException
4. xerox.ilu.IluUnexpectedException

#### ILU public classes

1. xerox.ilu.types.float128 A class for 128 bit floats.

2. xerox.ilu.Ilu The top level public interface to Ilu

3. xerox.ilu.IluAny Ilu's concrete class to holdCORBA::ANY

4. xerox.ilu.IluBatcher An IluBatcher represents a batching scope. Calls made within a batching scope are batched by the ILU runtime.

5. xerox.ilu.IluClassRep This represents an ilu class

6. xerox.ilu.IluCustomMapping An ilu type which supports custom mapping needs to register an object of IluCustomMapping-type to perform the actual transformation.

7. xerox.ilu.IluDataSupport An object implementation can help ILU by remembering internal data.

8. xerox.ilu.IluDebug The api is private, but the the command line flag interface is of interest to ilu users.

9. xerox.ilu.IluEnvironment The api is private.

10. xerox.ilu.IluIdentity Representation for ilu_IdentityInfo

11. xerox.ilu.IluIdentityType Representation for ilu_IdentityType

12. xerox.ilu.IluIHProposer A true object can support this interface to help Ilu in making up an instance handle. Ilu uses this method if an object is registered without providing an actual instance handle.

13. xerox.ilu.IluLifetimeArgs Keys to specify lifetime argumens of corba object

14. xerox.ilu.IluLifetimeForget Interface to specify lifetime argumens of ilu object

15. xerox.ilu.IluLifetimeRemember Interface to specify lifetime argumens of ilu object

16. org.omg.CORBA.Object Generic, client visible interface; super interface for all ilu objects (unless object type explicitly requires non-inheritance) Sadly has a few methods which are useless but must be implemented.

17. xerox.ilu.IluObjectBase Base super class used for surrogate object implementation. Class is client visible. This might as well be used as base class for true objects, at the discretion of the programmer (of the true object's class). In fact it is HIGHLY RECOMMENDED to extend this class if possible.

18. xerox.ilu.IluObjectTable An object table gives the application the ability to create true objects upon presentation of an instance handle. This is used by the application to pass in to the creation of a true server. This must be subclassed to be useful.

19. xerox.ilu.IluPassport Representation for ilu_Passport.

20. xerox.ilu.IluPickle Representation of typed values

21. xerox.ilu.IluPort This is the Java representation of the concept ilu_Port. Server applications should create ports with the IluServer interface. However this interface provides additional methods to destroy ports.

22. xerox.ilu.IluRootObjectHelper Corba style "Helper" class for the ilu root object.

23. xerox.ilu.IluRT0 Top level class. However we recommend using xerox.ilu.Ilu for all features available in xerox.ilu.Ilu and want to keep xerox.ilu.IluRT0 easier to be changed.

24. xerox.ilu.IluSerializationContext An IluSerializationContext represents an instance of the serialization guarantee. An instance is with respect to a particular server and set of calls. The guarantee is that the server application code receives calls in the same order as the client application code makes them, except that calls made after a barrier call can start service before calls made before the same barrier call. A barrier call is one that raises a system exception whose completion status is MAYBE (in CORBA terms, which are not quite right to use here) or that raises the barrier error. The client may not issue any two of these calls concurrently. <p> The way for a client to associate an IluSerializationContext is to attach the IluSerializationContext to the thread. This works only from IluServiceThread-s.

25. xerox.ilu.IluSBH String binding handle access. Parsing or composing SBH's takes the arguments and builds and IluSBH structure. The desired information then can be accessed with accessor functions. Currently IluSBH structure are immutable, however you should not rely on this immutability: future releases may or may not make this type more lightweight, mutable, and the fields unprotected.

26. xerox.ilu.IluServantFinalizable A server object can implement this interface to request a call of iluServantFinalize on its real finalization time. Please no resurection or other fancy usage.

27. xerox.ilu.IluServer This is the Java representation of the an ilu_Server. Only true objects have their servers accessible to clients

28. xerox.ilu.IluServerRelocation Interface used for clients which need to initiate server relocates.

29. xerox.ilu.IluServiceThread Subclass for certain ILU threads. This class is used to be able to transmit extra environment or thread specific information between the ILU kernel and its application. Threads forked by ILU for serving skeleton methods do use this thread class. Applications optionally may use this thread class when requiring service from ILU. Application use is optional.

30. xerox.ilu.IluSimpleBinding Simple binding for ILU.

31. xerox.ilu.IluTransportInfo Transport information is useful to describe servers.

32. xerox.ilu.IluTypeCode For representation of types...

33. xerox.ilu.IluTypeKind For representation of types...

#### Internal or esoteric classes

No public client use allowed or expected. Either because class is private for stubs or because it is esoteric in nature. The source of these classes documents why no use is excpected.

1. xerox.ilu.tools.gnh
2. xerox.ilu.tools.japp

1. xerox.ilu.corba_ServantFinalizer
2. xerox.ilu.IluAlarmTech
3. xerox.ilu.IluCall
4. xerox.ilu.IluClassAccess
5. xerox.ilu.IluConstantValueKind
6. xerox.ilu.IluDebugHooks
7. xerox.ilu.IluDebugWriter
8. xerox.ilu.IluExceptionRep
9. xerox.ilu.IluFactory
10. xerox.ilu.IluGCClient
11. xerox.ilu.IluInit
12. xerox.ilu.IluInit2
13. xerox.ilu.IluIOFunctions
14. xerox.ilu.IluMethodArgRep
15. xerox.ilu.IluMethodRep
16. xerox.ilu.IluOInt
17. xerox.ilu.IluServerConnection
18. xerox.ilu.IluSkeleton
19. xerox.ilu.IluWPBase
20. xerox.ilu.IluSurrogateConnection
21. xerox.ilu.IluSurrogateObject
22. xerox.ilu.IluTypeRep
23. xerox.ilu.IluUnixIdentityType

## Full 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; not basic types. In particular, 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; communicating ilu processes might not know whether or how an ilu type is custom 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 started using isl DOCUMENTATION options or stubber command line options, however there needs to be also runtime code which handles the conversion from and to the regular mapped object.

For full information, check the ILUSRC/etc/javaobv and the ILUSRC/examples/testjavaobv directories.

#### Stubbing

In an ISL interface the custom mapping can be specified with an interface DOCUMENTATION option:

    	DOCUMENTATION "JAVA-CUSTOMFILE" "description-file-name";

When stubbing the custom mapping could also be specified with an commandline option

    	-custom description-file-name

We are using a file to describe 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. 1) The name of the isl interface (which contains the isl type)
2. 2) The name of the isl type to be custom mapped
3. 3) The java class used to map the isl type into
4. 4) The java class which is used for holders
5. 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.)

1. -When you receive a subclass of the static ilu-type; that subclass info gets lost
2. -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.
3. -when the static class of an argument is a superclass of something with custom mapping on receive: 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)

### Java objects by value, Java marshalled objects

Ilu has a package which supports transmitting arbitrary java objects through ILU. To non-Java applications these look like regular ILU records containing bytes; to Java applications these are very specific Java classes.

This is implemented using full custom mapping using the java type java.lang.Object for ILU types and using java serialization to convert to and from regular ILU records at runtime.

The isl types xerox.ilujava.JavaObject is used to describe an arbitrary java.lang.Object. The java objects assigned to a ILU type ilujava.JavaObject are converted automaticly when transitting or receiving the objects. The Java application never sees the internal representation. Choose objects by value for direct communications between clients and servers which want to deal with life objects.

The isl types xerox.ilujava.MarshalledObject maps into a java object containing the serialized contents of a java object. Java objects are externalized or internalized explicitely before when converting to xerox.ilujava.MarshalledObject. The convertion routines are in the java class xerox.ilujava.IluMarshaller. Choose marshalled objects when the types are use in "dead" services which don't automaticly want to internalize the objects, e.g. For registrations in a name service or database.

Java objects must satisfy one of these conditions to be used as xerox.ilujava.JavaObject or xerox.ilujava.MarshalledObject.

1. Implement the java serializable interface
2. Ilu surrogate objects. Internalizing a MarshalledObject with a surrogate might turn the interned object into an ilu true object.
3. Ilu true objects, if they declare to implement the java serializable interface. The contents of the MarshalledObject will become a surrogate object.
4. Ilu enumerations, arrays, sequences, records, unions, but only if all element types can be serialized. (enumerations do not work correctly in jdk1.1; see javasoft's Bug Id 4163916)
5. The xerox.ilujava.MarshalledObject type itself (rather its custom record aequivalent)

Restriction on Ilu object types: When internalizing, the implementing Java class MUST be loaded. Ilu deserialization of Ilu types can not load implementations: At deserialization time ilu locks may be held which might prevent ilu type registrations. Given this general problem, we don't even bother storing the Java class with the sbh used to represent an ilu object type.

Of course, to a non-java applications both the xerox.ilujava.JavaObject and xerox.ilujava.MarshalledObject types look like their regular ISL records with gibberish sequences of bytes, as internalizing requires a Java VM.

Whether the classes are actually transmitted through the ilu connection or loaded by other means now is part of the state of the ilu-serialized object. The package generalizes over this aspect and class loading schemes can (MUST) be registered. Use the xerox.ilujava.IluMarshaller.setDefaultAccessMethod method.

The xerox.ilujava.IluMarshaller class has methods by which classloader functionality can be registered. (Method: xerox.ilujava.IluMarshaller.registerClassLoaderGetter).

The directory also contains a classloader which transmits class bytes through the same ilu connection. This classloader is unsafe, unless you can guarantee the true object of the classloader only sends valid and safe class bytes. Arbitrary mechanisms and security can be implemented using the registration mechanisms.

Another class loader is provided which loads the code through an URL. (This loader requires JDK1.2)

A more ideal world would decide on objects by value versus marshalled objects semantics on a more dynamic base. This is however difficult as they would need to be stubbed differently. Current ILU supports some choice dymamicly as it allows to transmit a xerox.ilujava.MarshalledObject where a xerox.ilujava.JavaObject is expected. In this case the other end will get a xerox.ilujava.MarshalledObject as expected; that is the reason xerox.ilujava.MarshalledObject are "serializable".

Users of Java objects by value or Java marshalled objects must make the classes available, e.g by putting the ILUHOME/lib/ilujavaobv.jar jar file onto the classpath.

For more information, check the ILUSRC/etc/javaobv directory.

An example application is in the ILUSRC/examples/testjavaobv directory. The demo program shows how to transmit arbitrary (though serializable) java objects.

This application even transmits Java classes (byte codes) through ilu. Unlike RMI, the class itself is passed through ILU. We do not claim the simpler mechanism of RMI wouldn't be sufficient, but by specifying access of the byte codes we can better show the power of the mechanisms.

#### Interoperability of Java objects by value, Java marshalled objects

ILU-serialization and Java-serialization

Do NOT confuse ILU's serialization to with java's standard serialization. The two mechanism are different, however they DO interact.

Ilu stubs do implement java.io.Serializable. This is in support of this package. Java-serialization and Java-de-serialization for some ILU types depends on substitution performed in this package and may not work with generic java-serializable applications, ie. RMI. Most ILU generated stubs work perfectly with RMI.

Java-Deserialization requires ILU being loaded.

Most important compatibility: Any java-serializable object can be ilu-serialized. The ILU MarshalledObject type is java-serializable.

ILU-serialization and Corba compatibility

The serialization adds features to ILU stubs. They do not interfere with the source code level compatibility. However standard Corba stubs will not have these features and would interfer with ILU-serialization.

The ISL types supporting serialized ILU objects contain no feature which couldn't be represented with standard IDL files, but the IDL file has not yet been written.

ILU-serialization and non-java ILU applications

To other other programming languages ILU-serialized objects look like ILU records with fields and sequences of bytes containing gibberish. The important point is: Such records can be handled, stored, and, passed along and become life again when forwarded into ILU for Java.

Go to the previous, next section.