org.eodisp.core.common
Interface ModelManagerRemote

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

ModelManagerRemoteImpl

public interface ModelManagerRemote
extends java.rmi.Remote

The remote interface of the model manager. This remote interface is used by the simulation manager to control federates on the model manager that shall participate in a federation execution.

Version:

$Id:$

Author:

ibirrer

Field Summary

static int	LOCK_TIMEOUT This is the time specifying how long a lock for a federate is valid.
static java.lang.String	REGISTRY_NAME

Method Summary

FederateProcessHandle	lockFederate(java.lang.String simulationManagerId, java.lang.String experimentName, java.lang.String federateId, java.lang.String federateVersion) Locks the federate with the given Id and version so that it is ready to be started by the calling simulation manager.
boolean	startFederate(FederateProcessHandle handle, java.net.URI crc, java.lang.String federationExecutionName, FileInitData[] fileInitData) Starts the federate that was previously locked using #lockFederate(String, String)}.
boolean	stopFederate(FederateProcessHandle federateProcessHandle) Stops the federate (process) with the given federate process handle.
void	updateLock(FederateProcessHandle handle) Updates a lock of a previously fetched handle.

Field Detail

REGISTRY_NAME

static final java.lang.String REGISTRY_NAME

See Also:

Constant Field Values

LOCK_TIMEOUT

static final int LOCK_TIMEOUT

This is the time specifying how long a lock for a federate is valid. Whether the lock for a federate persists also after this time has elapsed is implementation specific. You should therefore update the lock before this timeout elapses.

See Also:

updateLock(FederateProcessHandle), Constant Field Values

Method Detail

lockFederate

FederateProcessHandle lockFederate(java.lang.String simulationManagerId,
                                   java.lang.String experimentName,
                                   java.lang.String federateId,
                                   java.lang.String federateVersion)
                                   throws FederateNotKnownException,
                                          FederateAccessException,
                                          java.rmi.RemoteException

Locks the federate with the given Id and version so that it is ready to be started by the calling simulation manager. If the simulation manager does not start the federate within 5 minutes it unlocks the federate. If a simulation manager tries to start a federate with the returned process handle after the timeout has been reached, the #startFederate(FederateProcessHandle, URI, String, Map) throws a FederateStartException.

Parameters:

simulationManagerId - the ID of the simulation manager that wants to lock a federate.

experimentName - the name of the experiment

federateId - The ID of the federate that shall be started. This ID should be based on the reverse domain name convention (example: org.eodisp.example.rocket)

federateVersion - The version must have the following form:

      version ::=
         major( '.' minor ( '.' micro ( '.' qualifier )? )? )?
         major ::= number
         minor ::= number
         micro ::= number
         qualifier ::= ( alphanum | '_' | '-' )+
 

(copied from the OSGI standard)

Returns:

The handle which can be used to start the federate. null if the federate is already locked. Always returns a new handle if a federate can be started multiple times.

Throws:

FederateNotKnownException - thrown if the federate with the given federateId and version is not known on the model manager.

java.rmi.RemoteException - RMI remote exception happened while calling this method.

FederateAccessException

startFederate

boolean startFederate(FederateProcessHandle handle,
                      java.net.URI crc,
                      java.lang.String federationExecutionName,
                      FileInitData[] fileInitData)
                      throws FederateStartException,
                             java.rmi.RemoteException

Starts the federate that was previously locked using #lockFederate(String, String)}. This method also allows to send initialization data to the federate.

Parameters:

handle - A handle identifying a previously locked federate process.

crc - URI of the CRC that the newly started federate shall connect to

federationExecutionName - the name of the federation execution that the federate shall join.

fileInitData -

Initialization data as files for the federate to start. The elements of the array will be passed to the federate as command line argument in the same order as in the array.

                java Federate --init-data fileInitData[0],fileInitData[1],fileInitData[2]
            

Returns:

True, if the federate has been successfully started. False, if the federate cannot be started yet. This indicates that the request in principle is valid, but the federate is not yet ready to be started. You could then try to call this method until true (or an error) is returned.

Throws:

FederateStartException - thrown if the federate could not be started on the model manager.

java.rmi.RemoteException - RMI remote exception happened while calling this method.

updateLock

void updateLock(FederateProcessHandle handle)
                throws java.rmi.RemoteException

Updates a lock of a previously fetched handle. Updating a lock will ensure that a lock persists.

No error is thrown if the handle does not identify a valid federate. The request will be silently ignored.

Parameters:

handle - The previously fetched handle.

Throws:

java.rmi.RemoteException - RMI remote exception happened while calling this method.

See Also:

LOCK_TIMEOUT

stopFederate

boolean stopFederate(FederateProcessHandle federateProcessHandle)
                     throws java.rmi.RemoteException

Stops the federate (process) with the given federate process handle. It is guaranteed that the process with the given federate process ID is stopped if this method returns true.

Parameters:

federateProcessHandle - the handle of the federate process which shall be stopped. This handle must have been received by the {@link #lockFederate(String, String) method.

Returns:

return true if the federate process is stopped, false otherwise. It the federate was not running or if the federate handle is unknown by the model manager this method returns true. A false return value does does not indicate if the process is running or not.

Throws:

java.rmi.RemoteException - RMI remote exception happened while calling this method.