org.dvb.io.ixc
Class IxcRegistry

java.lang.Object
  extended by org.dvb.io.ixc.IxcRegistry

public class IxcRegistry
extends java.lang.Object

This is the bootstrap mechanism for obtaining references to remote objects residing in other Xlets executing on the same GEM terminal, using a URL-like syntax. The identification of a remote object is given using a syntax indicating the organisation ID and application ID:
/organisation_id/application_id/name
organisation_id = the organisation ID of the Xlet, as signalled in the application_identifier record, defined in the GEM specification.
application_id = the application ID of the Xlet, as signalled in the application_identifier record, defined in the GEM specification.
name = the name under which the remote object was exported.

The organisation ID and the application ID shall each be encoded as a hexadecimal string, as would be accepted by java.lang.Integer.parseInt(String s, 16).

When RMI is used to communicate over a network, stubs generated by a tool like rmic are often required. This is not necessary for inter-xlet communication initiated with IxcRegistry. If such stubs are present, they shall be ignored.

Similarly, network RMI objects often extend the class server.RemoteObject, in order to get appropriate implementations for Object.hashCode(), Object.equals(), and Object.toString(). Overriding Object's implementation of these methods in this way is not necessary for inter-xlet communication initiated with IxcRegistry, although it is not harmful. Note that the class server.RemoteObject is not required in all profiles.


Field Summary
static int GLOBAL
          Definition of the scope for bind or rebind - exported object is visible to any Xlet running within the same GEM terminal subject to requirements of the security model.
static int PAGE
          Definition of the scope for bind or rebind - exported object is only visible to Xlets within the same DVB-HTML application.
static int SERVICE
          Definition of the scope for bind or rebind - exported object is only visible to Xlets running within the same service context
 
Method Summary
static void bind(javax.tv.xlet.XletContext xc, java.lang.String name, java.rmi.Remote obj)
          Exports an object under a given name in the namespace of an Xlet.
static void bind(javax.tv.xlet.XletContext xc, java.lang.String name, java.rmi.Remote obj, int scope)
          Exports an object under a given name in the namespace of an Xlet.
static java.lang.String[] list(javax.tv.xlet.XletContext xc)
          Returns an array of string path objects available in the registry.
static java.rmi.Remote lookup(javax.tv.xlet.XletContext xc, java.lang.String path)
          Returns a remote object previously exported by an Xlet that has not been destroyed.
static void rebind(javax.tv.xlet.XletContext xc, java.lang.String name, java.rmi.Remote obj)
          Rebind the name to a new object in the context of an Xlet; replaces any existing binding.
static void rebind(javax.tv.xlet.XletContext xc, java.lang.String name, java.rmi.Remote obj, int scope)
          Rebind the name to a new object in the context of an Xlet; replaces any existing binding.
static void unbind(javax.tv.xlet.XletContext xc, java.lang.String name)
          Unbind the name.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SERVICE

public static final int SERVICE
Definition of the scope for bind or rebind - exported object is only visible to Xlets running within the same service context

Since:
MHP 1.1.2
See Also:
Constant Field Values

PAGE

public static final int PAGE
Definition of the scope for bind or rebind - exported object is only visible to Xlets within the same DVB-HTML application. Note that an embedded Xlet with a different app ID than its enclosing HTML page is still considered to be the same application as that which contains the enclosing page.

Since:
MHP 1.1.2
See Also:
Constant Field Values

GLOBAL

public static final int GLOBAL
Definition of the scope for bind or rebind - exported object is visible to any Xlet running within the same GEM terminal subject to requirements of the security model.

Since:
MHP 1.1.2
See Also:
Constant Field Values
Method Detail

lookup

public static java.rmi.Remote lookup(javax.tv.xlet.XletContext xc,
                                     java.lang.String path)
                              throws java.rmi.NotBoundException,
                                     java.rmi.RemoteException
Returns a remote object previously exported by an Xlet that has not been destroyed. The identification of a remote object is given using a syntax indicating the organisation ID and application ID:
/organisation_id/application_id/name
organisation_id = the organisation ID of the Xlet, as signalled in the application_identifier record.
application_id = the application ID of the Xlet, as signalled in the application_identifier record.
name = the name under which the remote object was exported.

The organisation ID and the application ID shall each be encoded as a hexadecimal string, as would be accepted by java.lang.Integer.parseInt(String s, 16). If the caller is not authorized to import a given object due to the security policy, then this API will behave as though the object had not been exported, that is, a NotBoundException shall be thrown.

Parameters:
xc - The context of the current Xlet (that is, the Xlet importing the object).
path - A file pathname-like string identifying the Xlet and the name of the object to be imported.
Returns:
A remote object
Throws:
java.rmi.NotBoundException - If the path is not currently bound.
java.rmi.RemoteException - If a remote stub class cannot be generated for the object being imported.
java.lang.IllegalArgumentException - If the path is not formatted in the syntax given above.
java.lang.NullPointerException - if path is null

bind

public static void bind(javax.tv.xlet.XletContext xc,
                        java.lang.String name,
                        java.rmi.Remote obj)
                 throws java.rmi.AlreadyBoundException
Exports an object under a given name in the namespace of an Xlet. The name can be any valid non-null String. No hierarchical namespace exists, e.g. the names "foo" and "bar/../foo" are distinct. If the exporting xlet has been destroyed, this method may fail silently.

The object shall be made visible to other applications running in the same service context. A call to bind(xc, name, obj) is thus equivalent to a call to bind(xc, name, obj, SERVICE).

Parameters:
xc - The context of the Xlet exporting the object.
name - The name identifying the object.
obj - The object being exported
Throws:
java.rmi.AlreadyBoundException - if this Xlet has previously exported an object under the given name.
java.lang.NullPointerException - if xc, name or obj is null

bind

public static void bind(javax.tv.xlet.XletContext xc,
                        java.lang.String name,
                        java.rmi.Remote obj,
                        int scope)
                 throws java.rmi.AlreadyBoundException
Exports an object under a given name in the namespace of an Xlet. The name can be any valid non-null String. No hierarchical namespace exists, e.g. the names "foo" and "bar/../foo" are distinct. If the exporting xlet has been destroyed, this method may fail silently.

Parameters:
xc - The context of the Xlet exporting the object.
name - The name identifying the object.
obj - The object being exported
scope - The scope to which the object is to be exported
Throws:
java.rmi.AlreadyBoundException - if this Xlet has previously exported an object under the given name.
java.lang.NullPointerException - if xc, name or obj is null
Since:
MHP 1.1

unbind

public static void unbind(javax.tv.xlet.XletContext xc,
                          java.lang.String name)
                   throws java.rmi.NotBoundException
Unbind the name.

Parameters:
xc - The context of the Xlet that exported the object to be unbound.
name - The name identifying the object.
Throws:
java.rmi.NotBoundException - if this is not currently any object exported by this Xlet under the given name.
java.lang.NullPointerException - if xc or name is null

rebind

public static void rebind(javax.tv.xlet.XletContext xc,
                          java.lang.String name,
                          java.rmi.Remote obj)
Rebind the name to a new object in the context of an Xlet; replaces any existing binding. The name can be any valid non-null String. No hierarchical namespace exists, e.g. the names "foo" and "bar/../foo" are distinct. If the exporting xlet has been destroyed, this method may fail silently.

The object shall be made visible to other applications running in the same service context. A call to rebind(xc, name, obj) is thus equivalent to a call to rebind(xc, name, obj, SERVICE).

Parameters:
xc - The context of the Xlet that exported the object.
name - The name identifying the object.
obj - The object being exported
Throws:
java.lang.NullPointerException - if xc, name or obj is null

rebind

public static void rebind(javax.tv.xlet.XletContext xc,
                          java.lang.String name,
                          java.rmi.Remote obj,
                          int scope)
Rebind the name to a new object in the context of an Xlet; replaces any existing binding. The name can be any valid non-null String. No hierarchical namespace exists, e.g. the names "foo" and "bar/../foo" are distinct. If the exporting xlet has been destroyed, this method may fail silently.

Narrowing the scope of the binding (e.g. from GLOBAL to SERVICE) shall have the same effect as a call to unbind for any applications which had references to that object and which were in scope but which are now out of scope.

Parameters:
xc - The context of the Xlet that exported the object.
name - The name identifying the object.
obj - The object being exported
scope - The scope to which the object is to be exported
Throws:
java.lang.NullPointerException - if xc, name or obj is null
Since:
MHP 1.1

list

public static java.lang.String[] list(javax.tv.xlet.XletContext xc)
Returns an array of string path objects available in the registry. The array contains a snapshot of the names present in the registry that the current Xlet would be allowed to import using IxcRegistry.lookup.

Parameters:
xc - The context of the current Xlet.
Returns:
A non-null array of strings containing a snapshot of the path names of all objects available to the caller in this registry.
See Also:
lookup(javax.tv.xlet.XletContext,String)