javax.microedition.xlet.ixc.package.html Maven / Gradle / Ivy
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 one or more remote interfaces. 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 identically named remote interfaces that
contain different declarations, the result of attempting to use these
interfaces for inter-Xlet communication is undefined, and possibly
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(s) that are implemented by the remote object.
It will include implementations of all methods
specified by the remote interface(s), 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.
The IXC implementation generates
all stub classes in the Xlet's class loader, that is, the class loader
returned by XletContext.getClassLoader() for the
XletContext passed to
IxcRegistry.getRegistry(XletContext).
Thus, applications must include the definition of any needed remote
interfaces in the search path of the main xlet class loader. Any
remote interfaces defined in class loaders created by the xlet
will not be found by the platform when attempting to generate
a stub class. Note that this does not apply to objects being
exported, only for objects being imported.
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 silently
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 remote interface type(s). 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.
- The type of 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
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.
Security Considerations
When a remote call is made, it will be executed within
an AccessControlContext that limits the set of granted
permissions. This AccessControlContext is that of the
creator of the IxcRegistry that is exporting the
object; it is obtained with AccessController.getContext()
in the first call to IxcRegistry.getRegistry(XletContext)
for a given XletContext instance.
See {@link java.security.AccessController}
and {@link java.security.AccessControlContext} for information about this
mechanism.
Inter-xlet communication will work with any valid
XletContext, that is, with any XletContext
that returns a
valid, non-null ClassLoader. This class loader will be used
to load the automatically generated stub classes.
Access to ClassLoader
instances from application code is
limited. See java.lang.RuntimePermission("getClassLoader")
for details.
@see javax.microedition.xlet.ixc.IxcRegistry
@see java.rmi.Remote
@see java.rmi.registry.Registry