org.objectweb.jac.core.dist
Class RemoteRef

java.lang.Object
  |
  +--org.objectweb.jac.core.dist.RemoteRef
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
RMIRemoteRef

public class RemoteRef
extends Object
implements Serializable

RemoteRef stores the reference of a remote object. The way the remote object is accessed depends on the underlying communication protocol (eg CORBA or RMI).

Supporting a new communication protocol requires to subclass RemoteRef (eg RMIRemoteRef or CORBARemoteRef) and to implement the resolve and reresolve methods.

Author:
Lionel Seinturier, Renaud Pawlak
See Also:
resolve(java.lang.String), reresolve(), RMIRemoteRef, Serialized Form

Field Summary
protected  String name
          The name of the remote object that is of will be associated to the remote ref.
protected  RemoteContainer remCont
          The reference of the container that handles the remote object.
protected  int remIndex
          The index (see org.objectweb.jac.core.JacObject) of the remote object.
protected static String toAdaptProp
          Following constants are property keys used by remoteNew().
 
Constructor Summary
protected RemoteRef()
          Empty default constructor for RemoteRef needed by the compiler whenever RemoteRef is subclasses (eg RMIRemoteRef or CORBARemoteRef).
  RemoteRef(RemoteContainer remCont, int remIndex)
          This is a full constructor for RemoteRef.
  RemoteRef(String remCont, int remIndex)
          This is a more friendly constructor for RemoteRef.
 
Method Summary
static RemoteRef create(String name)
          This class method returns a new RemoteRef object.
static RemoteRef create(String name, Object localObject)
          Create a remote reference from a local JAC object (in order, for example, to transmit it to a remote container).
static RemoteRef create(String name, RemoteContainer remCont, int remIndex)
          This class method returns a remote reference for an existing remote JAC object.
 boolean equals(Object o)
          Test the equality of 2 remote references.
 String getName()
          The getter method for the name.
 RemoteContainer getRemCont()
          The getter method for the remCont field.
 int getRemIndex()
          The getter method for the remIndex field.
 Object invoke(String methodName, Object[] methodArgs)
          Forward a call to the referenced object.
 Object invoke(String methodName, Object[] methodArgs, Boolean[] refs)
          Forward a call to the referenced object.
 Object invokeRoleMethod(String methodName, Object[] methodArgs)
          Forward a role method call to the referenced object.
 void remoteCopy(Object src)
          Copy the state of a given object into the remote object referenced by the current reference.
 void remoteCopy(Object src, String[] fieldsName)
          Copy the state of a given object into the remote object referenced by the current reference.
 void remoteNew(String host, String clName)
          Remotely instantiate a class.
 void remoteNew(String host, String clName, Object[] args)
          Remotely instantiate a class.
 void remoteNewWithCopy(String host, String clName, Object src)
          Remotely instantiate a class.
 void remoteNewWithCopy(String host, String clName, Object[] args, Object src)
          Remotely instantiate a class.
 void remoteNewWithCopy(String host, String clName, Object[] args, Object src, String[] fieldsName)
          Remotely instantiate a class.
 void remoteNewWithCopy(String host, String clName, Object src, String[] fieldsName)
          Remotely instantiate a class.
 RemoteContainer reresolve()
          This method re-gets the reference of a remote container.
 RemoteContainer resolve(String contName)
          This method resolves a container from a container name.
 void setName(String name)
          The setter method for the name.
 String toString()
          Create a textual representation of the remote reference.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

remCont

protected RemoteContainer remCont
The reference of the container that handles the remote object.


remIndex

protected int remIndex
The index (see org.objectweb.jac.core.JacObject) of the remote object.


name

protected String name
The name of the remote object that is of will be associated to the remote ref.


toAdaptProp

protected static final String toAdaptProp
Following constants are property keys used by remoteNew().

See Also:
Constant Field Values
Constructor Detail

RemoteRef

public RemoteRef(RemoteContainer remCont,
                 int remIndex)
This is a full constructor for RemoteRef.

Parameters:
remCont - the ref of the container that handles the remote object.
remIndex - the index of the remote object

RemoteRef

public RemoteRef(String remCont,
                 int remIndex)
This is a more friendly constructor for RemoteRef.

Parameters:
remCont - the name of the container that handles the remote object.
remIndex - the index of the remote object.

RemoteRef

protected RemoteRef()
Empty default constructor for RemoteRef needed by the compiler whenever RemoteRef is subclasses (eg RMIRemoteRef or CORBARemoteRef).

This constructor should never be called in other cases (this is why it is protected).

Method Detail

create

public static RemoteRef create(String name)
This class method returns a new RemoteRef object.

Property org.objectweb.jac.dist.remoteRefClass defines the class of the actual RemoteRef returned (e.g. CORBARemoteRef). If the property is not defined or if the class does not exist, RMIRemoteRef is the default.

Parameters:
name - the name to give to the remote ref (should be equal to the pointed object name)
Returns:
a new RemoteRef object

create

public static RemoteRef create(String name,
                               RemoteContainer remCont,
                               int remIndex)
This class method returns a remote reference for an existing remote JAC object.

Property org.objectweb.jac.dist.remoteRefClass defines the class of the actual RemoteRef returned (e.g. CORBARemoteRef). If the property is not defined or if the class does not exist, RMIRemoteRef is the default.

Parameters:
name - the remote object name (can be null if not needed)
remCont - the remote container where the JAC object is instantiated
remIndex - the index of the JAC object in the remote container
Returns:
the remote reference of the JAC object

create

public static RemoteRef create(String name,
                               Object localObject)
Create a remote reference from a local JAC object (in order, for example, to transmit it to a remote container).

Parameters:
name - the name to be given to the remote reference
localObject - the object to create the reference from
Returns:
the new remote reference

getRemCont

public RemoteContainer getRemCont()
The getter method for the remCont field.

It returns a the container that handles the remote object. If the remote container is local, then the object pointed by the remote reference is also local.

Returns:
the remCont field value

setName

public void setName(String name)
The setter method for the name.

Parameters:
name - the new name

getName

public String getName()
The getter method for the name.

Returns:
the reference name

getRemIndex

public int getRemIndex()
The getter method for the remIndex field.

remIndex is the index (see org.objectweb.jac.core.JacObject) of the remote object.

Returns:
the remIndex field value

resolve

public RemoteContainer resolve(String contName)
This method resolves a container from a container name.

Its implementation is protocol dependent (eg RMI or CORBA). Most concrete implementations of this method (see RMIRemoteRef) simply delegate the resolution to a resolve() class method defined in a container class (see RMIRemoteContainer).

Parameters:
contName - the name of the container
Returns:
the container
See Also:
RMIRemoteRef.resolve(String)

reresolve

public RemoteContainer reresolve()
This method re-gets the reference of a remote container.

Its implementation is protocol dependent (eg RMI or CORBA). Some communication protocols (eg CORBA) do not linearalize remote references in a standard way. Thus a remote reference may need to be adapted whenever it is transmitted.

This method is called when a remote reference is recieved by a RemoteContainer.

Returns:
the container reference
See Also:
RMIRemoteRef.reresolve()

remoteNew

public void remoteNew(String host,
                      String clName)
Remotely instantiate a class.

Make the current RemoteRef instance reference the created object.

Parameters:
host - the host machine
clName - the class to instantiate

remoteNew

public void remoteNew(String host,
                      String clName,
                      Object[] args)
Remotely instantiate a class.

Make the current RemoteRef instance reference the created object.

Parameters:
host - the host machine
clName - the class to instantiate
args - initialization arguments for the instantiation

remoteNewWithCopy

public void remoteNewWithCopy(String host,
                              String clName,
                              Object src)
Remotely instantiate a class.

Make the current RemoteRef instance reference the created object and copy the state of the given object into the remote object.

All the fields of the object are copied.

Parameters:
host - the host machine
clName - the class to instantiate
src - the source object containing the data to copy

remoteNewWithCopy

public void remoteNewWithCopy(String host,
                              String clName,
                              Object[] args,
                              Object src)
Remotely instantiate a class.

Make the current RemoteRef instance reference the created object and copy the state of the given object into the remote object.

All the fields of the object are copied.

Parameters:
host - the host machine
clName - the class to instantiate
args - initialization arguments for the instantiation
src - the source object containing the data to copy

remoteNewWithCopy

public void remoteNewWithCopy(String host,
                              String clName,
                              Object src,
                              String[] fieldsName)
Remotely instantiate a class.

Make the current RemoteRef instance reference the created object and copy the state of the given object into the remote object.

Only specified fields are copied.

Parameters:
host - the host machine
clName - the class to instantiate
src - the source object containing the data to copy
fieldsName - the fields name to copy

remoteNewWithCopy

public void remoteNewWithCopy(String host,
                              String clName,
                              Object[] args,
                              Object src,
                              String[] fieldsName)
Remotely instantiate a class. Make the current RemoteRef instance reference the created object and copy the state of the given object into the remote object.

Only specified fields are copied.

Parameters:
host - the host machine
clName - the class to instantiate
args - initialization arguments for the instantiation
src - the source object containing the data to copy
fieldsName - the fields name to copy

remoteCopy

public void remoteCopy(Object src)
Copy the state of a given object into the remote object referenced by the current reference.

All the fields of the object are copied.

Parameters:
src - the source object containing the data to copy

remoteCopy

public void remoteCopy(Object src,
                       String[] fieldsName)
Copy the state of a given object into the remote object referenced by the current reference.

Only specified fields are copied.

Parameters:
src - the source object containing the data to copy
fieldsName - the fields name to copy

invoke

public Object invoke(String methodName,
                     Object[] methodArgs)
Forward a call to the referenced object.

Parameters:
methodName - the called method name
methodArgs - the called method arguments
Returns:
the result

invoke

public Object invoke(String methodName,
                     Object[] methodArgs,
                     Boolean[] refs)
Forward a call to the referenced object.

Parameters:
methodName - the called method name
methodArgs - the called method arguments
Returns:
the result

invokeRoleMethod

public Object invokeRoleMethod(String methodName,
                               Object[] methodArgs)
Forward a role method call to the referenced object.

Parameters:
methodName - the called role method name
methodArgs - the called role method arguments
Returns:
the result

toString

public String toString()
Create a textual representation of the remote reference.

Overrides:
toString in class Object
Returns:
the textual representation of the current reference

equals

public boolean equals(Object o)
Test the equality of 2 remote references.

Overrides:
equals in class Object
Parameters:
o - the remote reference to check
Returns:
true if equals the current one