org.objectweb.jonathan.binding.api

Interface Identifier

Known Implementing Classes:
EBinder.EId

public interface Identifier

An identifier uniquely identifies an applicative object interface in a given naming context. It is a specific kind of name.

Method Summary

Object
bind(Identifier ref, Context hints)
The bind operation returns an object giving access to the object interface referenced by the target identifier.
byte[]
encode()
Encodes the target identifier in an array of bytes.
void
encode(Marshaller m)
Encodes the target identifier in a marshaller.
NamingContext
getContext()
Returns the naming context associated with the target identifier.
boolean
isValid()
Tests the validity of the target identifier.
Object
resolve()
Returns the next name in the referencing chain.
void
unexport()
Unexporting an identifier means that the target identifier no longer designates the object interface it was created for (by some export method).

Method Details

bind

public Object bind(Identifier ref,
                   Context hints)
            throws ForwardException,
                   BindException,
                   JonathanException
The bind operation returns an object giving access to the object interface referenced by the target identifier.

The returned object may be a direct reference to the object interface that was used to create the identifier (at export-time), or it may be a surrogate (a proxy) for that object interface.

If this operation is implemented, it means that the related naming context is not only a naming context but also a binder.

This operation may in particular raise two types of exceptions:

  • ForwardExceptions that indicate that the "real" target object interface should be bound using the reference contained in the exception. Note that in this case, calling the resolve method should return the same reference. This facility may be used to handle mobility.
  • BindExceptions that indicate that an error occurred in the binding process;

All parameters are optional (they may be null).

  • The ref parameter is an array of identifiers, to which the target identifier should belong: Object interfaces may be identified by several identifiers, and it is useful to maintain this list of identifiers, even if only one identifier is used to actually give access to the designated object interface. This parameter has been added as a convenience to achieve this, but it may not be meaningfull in all cases.
  • The hints parameter contains information that may be required by naming contexts to build the returned object. Here again, it may not be meaningfull in all cases.

Parameters:
ref - a set of identifiers of the seeked object interface;
hints - a context containing extra information that may be useful;

Returns:
a reference to the seeked interface.

Throws:
ForwardException - if the target has moved;
BindException - if an error occurs in the binding process;

See Also:
org.objectweb.jonathan.model.binder.bind(org.objectweb.jonathan.model.name)


encode

public byte[] encode()
            throws JonathanException

Returns:
an array of bytes encoding the target identifier.


encode

public void encode(Marshaller m)
            throws JonathanException
Encodes the target identifier in a marshaller.

Parameters:


getContext

public NamingContext getContext()
Returns the naming context associated with the target identifier. An identifier is always associated the naming context that created it.

Returns:
the naming context associated with the target identifier.


isValid

public boolean isValid()
Tests the validity of the target identifier. A false return means that a call to either bind or resolve will fail. If so, the target identifier must no longer be used. resolve certainly fail.

Returns:
false if calls to either bind or


resolve

public Object resolve()

Returns:
the next name in the referencing chain.

See Also:
org.objectweb.jonathan.model.naming_context.resolve(org.objectweb.jonathan.model.name)


unexport

public void unexport()
Unexporting an identifier means that the target identifier no longer designates the object interface it was created for (by some export method). An identifier must no longer be used after it has been "unexported".