Package javax.microedition.xlet.ixc

Provides facilities for inter-Xlet communication (IXC).

See:
Description

Class Summary

IxcRegistry

IxcRegistry is the bootstrap mechanism for obtaining references to remote objects residing in other Xlets executing on the same machine, but in separate classloaders.

Exception Summary

StubException

StubException is thrown whenever stub class generation fails for inter-Xlet communication.

Package javax.microedition.xlet.ixc Description

Provides facilities for inter-Xlet communication (IXC). The class IXCRegistry is the bootstrap mechanism for obtaining references to remote objects residing in other Xlets executing on the same machine, but in separate classloaders.

Remote Call Semantics

An object may be communicated to another Xlet in two ways: A reference to the remote object can be passed, or a copy of the remote object can be made. These two techniques are called as pass by remote reference, and pass by remote copy. When an object that has been bound to the IXC Registry via a method of javax.microedition.xlet.ixc.IxcRegistry is imported by another, it shall be passed by remote reference.

Objects Passed by Remote Reference

An object that is passed by remote reference must implement a remote interface. A remote interface is an interface that extends, either directly or indirectly, the marker interface java.rmi.Remote. The declared type of a parameter or a return value for a remote method invocation must be a remote interface, or a class whose instances are serializable. If a remote interface that is application-defined, the interface definition must be included in both the sending and receiving Xlet. If the two xlets contain an identically named remote interfaces that contain different declarations, the result of attempting to use these interfaces for inter-Xlet communication is undefined, and possible implementation dependent.

When an object is passed by remote reference to a different Xlet, the receiving Xlet does not receive a direct reference to the exported object; rather, it receives an instance of a stub class. This stub class will not be a subclass of the remote object's runtime type; rather, it will be a platform-generated class that implements the remote interface type that is the declared type of the argument or return value. It will include implementations of all methods specified by the remote interface, and will contain no other members accessible to the application. These methods are called "remote methods". Remote methods invoked on this stub class instance will be forwarded to the object in the original Xlet, and executed in the context of that Xlet.

Note: The remote methods specified by a remote interface include all methods specified by that interface, including the methods inherited from superinterfaces. This applies even for methods inherited from superinterfaces that do not themselves extend java.rmi.Remote, either directly or indirectly.
The definition of the stub class shall be automatically created by the platform. This differs from traditional network RMI as implemented in Sun platforms through JDK 1.3, where the stub classes are created by the developer using a tool such as rmic. If stub classes produced by rmic or any other off-line tool are present, the platform shall silent ignore them for the purposes of inter-Xlet communication.

The stub class that is generated shall include a definition for all of the methods specified by the declared remote interface type. A remote interface is an interface that extends java.rmi.Remote, either directly or indirectly. These remote methods must be declared as follows:

• Each method must declare java.rmi.RemoteException in its throws clause, in addition to any application-specific exceptions.
• A remote object passed by remote reference as an argument or return value must be declared as an interface that extends java.rmi.Remote , and not as an application class that implements this remote interface.
• The type of each method argument must either be a remote interface, a class or interface that implements java.io.Serializable, or a primitive type.
• Each return value must either be a remote interface, a class or interface that implements java.io.Serializable, a primitive type, or void.

If any remote method does not follow these rules, the platform cannot generate a stub class. When one is required, a StubException shall instead be thrown to the caller.

Lifecycle Considerations for Remote Objects

When an Xlet is destroyed, the objects it has exported are unbound from the IXC registry. However, it is possible that other Xlets may still have remote references to some of the Xlet's objects. If a method is invoked on one of these remote objects, the platform may fail to execute the method, and instead throw a RemoteException. If a remote method call is in progress when the Xlet receiving the call is destroyed, the calling Xlet may receive a RemoteException on the calling thread, and the remote method invocation may be abruptly terminated. If a remote method has started executing code in the implementation of the remote object when the Xlet making the call is destroyed, the call shall run to completion, unless the Xlet receiving the call is also destroyed.

Exceptions in Remote Method Calls

If an exception is thrown from a remote method, a remote copy of that exception shall be made in the context of the calling Xlet. This copy of the exception shall be thrown to the caller.

Re-exported Objects

It is possible that an object passed from one Xlet to another might be passed back to the original Xlet. This could happen through any number of intervening Xlets. If this happens, the original Xlet will receive the instance that it originally exported. If it compares the instance it receives with the original instance using the Java == operator, the result will be true. Because of this, there is no need to provide an override of java.lang.Object.equals() or java.lang.Object.hashCode() for remote objects.

This behavior is different than network RMI, as implemented in Sun's JDK through 1.3. In Sun's implementation of network RMI, a remote stub object is given to the original Xlet, but stubs and remote objects are required to have a special version of the equals() and hashCode() methods.

Objects Passed by Remote Copy

An object is passed by remote copy when a method argument or return value is passed, where the class of that object does not implement java.rmi.Remote . Additionally, a remote method call exception is communicated to the receiving Xlet by remote copy, as described above.

When an object is passed by remote copy, it is serialized into a byte stream in the context of the exporting Xlet, and deserialized in the context of the importing Xlet. Serialization is performed as defined for java.io.Serializable . Application-defined classes may be serialized, but the definition of the application-defined class must be present in both Xlets, and the external forms of both versions of the class must be compatible. If any error in serialization or de-serialization occurs, an instance of java.rmi.RemoteException shall be thrown.

Treatment of Primitive Types

Primitive types passed as method arguments or return values are copied.

Classloading Considerations

The presence of inter-xlet communication does not allow the loading of one Xlet's classes from another. No classloader that loads classes from a remote Xlet for remote method calls is created (unlike network RMI, which creates a special RMIClassLoader for remote objects). Rather, a copy of each application-defined remote interface and serializable object involved in a remote method invocation must be present in both Xlets. If this is not the case, the platform shall generate a RemoteException and throw it in the calling thread.

Thread Usage

A remote method may or may not execute in separate underlying thread. If an application makes a remote method invocation to a remote object in a different application, and that second application calls back to the first in the same “thread,” then the first application might or might not observe that the original calling thread and the callback thread are the same instance of java.lang.Thread.

If an application makes simultaneous remote calls in separate threads, then the remote execution shall appear to be carried out in parallel.

Note: This is not meant to rule out thread-pooling techniques. Specifically, an implementation may choose to serialize such remote calls, as long as the first one completes within a reasonably short time, relative to the normal scheduling rules of Java threads.

Garbage Collection of Remote Objects

When a non-destroyed Xlet contains a reachable instance of a stub for a remote object, that remote object shall not be garbage collected, unless the remote Xlet is destroyed. When an exported object no longer has any remote stub objects that are reachable in other non-destroyed Xlets, and when that exported object is also not reachable locally within its Xlet, then that remote object shall be considered unreachable, and thus eligible for reclamation.

When an Xlet is destroyed, other Xlets may hold remote references to objects within the Xlet being destroyed. In this case, the referenced objects may be dereferenced and ultimately garbage collected. If this is done, then attempts to invoke remote methods on these objects shall result in a RemoteException to the caller.

See Also:

IxcRegistry, Remote,