Go to the previous, next section.
ILU for Java is CORBA compatible. Compatibility is a word from the english language; in case of ILU we mean mainly two things:
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.
Sadly ILU for Java's compatibility is not perfect. Not all CORBA functions are implemented. More noticable is however the fact that we do only try to achieve source compatibility; there is no binary compatibility available.
Compatibility requires the programmers help: Not all programs will be compatible, but it is possible to write compatible programs.
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 or in other formats http://www.omg.org/corba/cichpter.htm#mijav
If ILU for Java is used in standard mapping mode, its naming scheme matches the CORBA standard. Even resolution of naming conflicts is mostly CORBA compatible. However for some conflicts there might be slight differences, and, Ilu considers certain names to be conflicting which have not been mentioned in the corba standard.
In particular ILU considers methods names used by the java.lang.Object class to be "reserved" and causing conflicts. Not doing so would generate confusing errors if a generated method would conflict with a standard method by using identical arguments.
See the CORBA standard for modules.
An ISL interface is mapped to a Java package with the same name.
There is a stubber option to put a prefix to the Java package, to make it a nested package.
Avoid IDL features which are not in the scope of a idl module (= ISL Interface).
See the corba standard.
The "new" extended IDL types fixed is not yet supported.
128 bit floating point values are carried around as "xerox.ilu.types.float128" but no operations are available.
In case of "byte", ILU carries the bit pattern, not the numerical value.
See the corba standard.
See the corba standard.
See the corba standard for ANY and Typecodes.
See the corba standard.
See the corba standard.
See the corba standard.
See the corba standard.
See the corba standard.
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.
See the CORBA standard for "corba interfaces".
To request creation of an object the createTrueObjectcreateTrueObjectsuper.returnTrueObject
True object have to implement all the interfaces required by their type.
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 or the class org.omg.CORBA.portable.ObjectImpl. 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.
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.
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. 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: ilu's version of org.omg.CORBA.portable.ObjectImpl.java simply extends xerox.ilu.IluObjectBase)
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.
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.
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
An IluServer instance can be created by calling the function
ilu.createServer([serverID])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 defaultServerSystem.err
An object of type IluServerserverId()
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 are defined in the class IluObjectTable. To define an
object table one subclasses IluObjectTableIluServerIluObjectTableIluServer
Because the Object Tables calls are made with internal ILU locks held, it must not do recursive calls into ILU.
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
Record types can be subclassed. The subclass can register itself with the original (stub) class.
"Custom Records" class assign their own class to a (protected) java.lang.Class variable 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.
Surrogate creation can be intercepted. To do so one registers either a
Java class, or, a factory object with the stub class
implementing a object type. See the methods
IluClassRep.setSurrClassIluClassRep.setSurrFactory
The class xerox.ilu.IluSBH
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)
As alternative to IluSimpleBinding, the resolve_initial_references
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.
Please read the introductory section on "Java Administrativia Without ILU" first.
This section will be required knowledge when we explain how to do Java administrativia WITH ILU later.
The first time you see any of the standard Java tree structures you are bound to be overwhelmed. However, it is not that bad if you know some of the reasoning. If you have a good understanding of the Java system building concepts without ILU, you will tolerate Java with ILU much better.
The Java compiler takes Java sources and creates binaries, typically called class files. (Never mind, that the word "class" has as a meaning in the source domain as well).
The Java compiler conceptually copes with 4 file hierarchies.
Sad to say, Sun's documentation is not conceptually clean. The functionality is different when directories are specified as command line options or with environment variables. It feels to us as if Sun changes the behaviour with every Java release.
make files, I recommend compiling multiple sources with one single
compile command and letting the Java compiler worry about
dependencies.)
-classpath command
line switch or the CLASSPATH environment variable. The semantics
are different! The -classpath command line switch must be
complete (including system binaries), but if the CLASSPATH
environment variable is used, the standard binaries are automatically
accessed. You can work either way, if you know the difference.
Sadly to say with jdk1.2beta3 (but not jdk1.2beta2) using the CLASSPATH: classes defined by Sun are found before user defined classes, even if the CLASSPATH names the user defined class first. Using the -classpath command
line switch however finds the classes in proper order (but you need to add the system classes to the path).
In jdk1.2beta4 it is no more possible to replace "bootstrap" classes using CLASSPATH
or -classpath. However a new -Xbootclasspath command line option
allows (and is required) to treat ilu classes like "bootstrap" classes. This doesn't work right out the box; more later.
Some experiments suggest that the compiler may also on the fly generate binaries when needed... We don't rely on this.
-d option allows one to specify a
directory. In the absence of the -d option the compiler uses the
working directory. With the -d option binaries are stored
hierarchically in the destination directory, according to their package
structure. Without the -d option binaries are stored
directly in the curent working directory. Recommendation: Always use
the -d option. If the -d option is not used some
Java tools will not find the binaries... Don't get confused
that "Hello World" programs can be compiled without -d option;
real programs can't.
CLASSPATH environment
variable. Be warned, that is the same environment variable used
to locate pre-compiled input sources.
To make matters worse:
An application programmer will face the decision whether the implementation for true object should be in the package designated for stubs, or in a package of its own. Both choices do make sense; ILU will work either way and doesn't make that decision for you. In general we expect most applications to prefer working in one single package. However we can imagine scenarios where for security reasons a stub could be trusted but a server object might not be trusted, or they'd be signed independently by different entities.
But please: Don't ever write Java code which is not in a package at all. You will end up putting it in a package later anyway. It will be much more work to do that later than to, at the very beginning, set up all your commands and files to work with a package.
We recommend a compiler usage by which the input, independent of its structure, is compiled into a hierarchical file structure depending from a directory called `./classes'.
We also recommend putting the `./classes' directory into the
CLASSPATH so that the Java loader finds the compiled binaries.
The ILU runtime is in the Java package
xerox.iluIlu
With jdk1.2beta3 don't use CLASSPATH for output but use the -classpath command line argument. The problem is the same for both the "java" and the "javac" command.
With jdk1.2beta4 "bootclasses" can not be overwritten with the CLASSPATH environment variable or the -classpath command line argument. However, the standard "bootclasses" DO contain INCOMPATIBLE org.omg packages. You will have to use the new -Xbootclasspath option to treat ilu classes as "bootclasses".
This doesn't exactly work: There is a bug in jdk1.2beta4 which makes the loader for native code miss Ilu when Ilu is on the bootclass path; (The bootclass loader ignores LD_LIBRARY_PATH)
Two possible work arounds:
1) In a FUTURE jdk (NOT jdk1.2beta4) there might be a sun.boot.library.path property. This property need to include the ilu native binaries (in addition to the jre binaries) to make java find them, if Ilu is loaded with the bootclass loader.
Example:
java -Xbootclasspath:${ILUHOME}/lib/ilu.jar:${java-s-home}/jre/lib/rt.jar -Dsun.boot.library.path=${ILUHOME}/lib:${java-s-home}/jre/lib/sparc YourApplication
2) If your license allows this: Simply remove Suns version of the org.omg classes from the rt.jar file. Ilu then can be loaded with the standard class loader; this will completely avoid that bootclass loader bug.
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. For the
same reason a file with a list of generated Java files is
generated.
The stubber recognizes the following options or switches:
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.
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.
CLASSPATH environment variable.
CLASSPATH
environment variable.
CLASSPATH environment variable. (Some of these files win the or.omg class
conflict with corresponding implementations deliverd by Sun microsystems. Make sure Ilu's
files are found first.)
Java JDK 1.1.4 starts to garbage collect classes. (This class collection is too agressive, see below). ILU carefully stuffs data into static variables to prevent garbage collection. These two paradigms do not work nicely together. To prevent memory smashes, the -noclassgc switch is recommended whenever executing any Java program with jdk 1.1.4 and jdk 1.1.5 if it uses ILU.
There is a known bug in JDK about collection of classes. Furthermore there is a Java language change for collection of classes planned. This language change will prevent collection of classes until their class loader is collected. ILU will become simpler once the language change is implemented.
If your java system does not support jar files, the classes are compiled into `ILUHOME/lib/javaclasses/'. The reason for this non-standard place is the fact that some ILU developers believe the subdirectory `./classes/' should be reserved for some other purpose.
LD_LIBRARY_PATH. The path must have an entry pointing into the
ILU Java runtime directory.
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
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.
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.
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. Objects of this class then are 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()xerox.ilu.Ilu.registerTrueObject
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.
A client program may obtain a reference to an ILU object in one of the following ways:
objectFromSBH()xerox.ilu.Ilu.objectFromSBH(sbh, cl)square from
INTERFACE shapes, which has a string binding handle sbh,
one would call xerox.ilu.Ilu.objectFromSBH(sbh, shapes.square)xerox.ilu.IluSimpleBinding.lookup(sid,
ih, cl)INOUT or OUT parameter.
Use of ILU in applets is not impossible, but it is not fully supported either. Currently, using of ILU in applets is only recommended for intranet usage but not for generic internet applications.
There are really three problems:
ILU for Java is not BINARY CORBA compatible. You can not receive arbitrary non ILU stubs and execute those onb top of Ilu. You have to set up your classpath so that ILU applications load ILU and not another orb. This is insofar problematic: If you want your browser to host refular corba applets and ilu using applets there is a class conflict problem. This conflict problem can be fixed by using (different) java-plugin, each set up with the class path appropriately.
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 by loading ILU on the classpath, or by using signed signed applets. 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).
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.
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.
Please see the "Java" subsection of "Building ILU" in the chapter section Using ILU with Microsoft Windows.
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".
Only unix supports green threads. Unless disabled, ilu will build both version and dynamicly tries to load whichever version works. Sadly we do not know how to determine whether java is using green threads or native threads. Sadly the native code of ilu is different in those two cases. Ilu simply tries one version, and, if it throws an exception Ilu tries the other version. (Never mind that the java vm doesn't throw exceptions bu crashes if tried in the wrong order)
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.12beta... each in the same directory. This works because the by accident or design, the java classes for jdk 1.1 and jdk1.12beta are compatible. Ilu at runtime decides which version of the native libraries to load.
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 is about the worst documentation package I have encountered sofar. Nevertheless, 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 javadoc index is empty. For some reason javasoft prefers to document this bug instead of fixing it.
javadoc documents features which are not to be used by applications. This is an ILU problem as ILU declares many features public simply to make them available to stubs.
It would be nice if javadoc documentation would have links to the source code.
javadoc has problems handling files in a flat directory, but the java runtime now has been changed to use a hierarchical directory.
With jdk-1.1 you need to manually create an images subdirectory and copy the images. (Ask javasoft why). 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.
# 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.2beta3) # (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/* .
A means to pass a CORBA things as a reference parameter. Holder classes are mutable.
Some of these 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.
The way resolve_initial_references
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.
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 -Dilu.load=org.omg.CosNaming._allJavaStubs:MyApplication._allJavaStubs -DNameService=IOR:000000000000002849444C3A6F6D672E6F72672F436F734E616D696E672F4E616D696E67436F6E746578743A312E300000000001494C55000000009A0001000000000092696C753A31332E322E3131362E33322E336461342E33343663396337302E312F31332E322E3131362E33322E336461342E33343663396337302E303B49444C2533416F6D672E6F7267253246436F734E616D696E672532464E616D696E67436F6E74657874253341312E303B73756E7270634073756E727063726D3D7463705F31332E322E3131362E33325F333439373700 startMyApplication
or maybe
java -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 registered before an object of that type is read, otherwise the type information will be lost.
These classes are public, but not necessarily considered part of ilu.
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.
Remembers objects; better then using static variables as VMExtras also deals with collecting classes.
High priority thread introducing proper timeslicing into the Java vm.
xerox.ilu.IluBadParameterException
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.
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.
For full information, check the ILUSRC/examples/javaserial directory
When stubbing the custom mapping needs to be specified with an commandline option
-custom description-file-nameWe 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.
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.)
This application program defines a full custom mapping using the java type java.lang.Object. It furthermore uses java serialization to implement the runtime conversion.
The test program for the application program shows how to transmit arbitrary (though serializable) java objects.
For full information, check the ILUSRC/examples/javaserial directory
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 using full custom mapping.
Go to the previous, next section.