net.openwings.container
Interface Container

All Known Subinterfaces:

ContainerManager

public interface Container

This interface provides the key abstraction for Container Services. A Container describes a service interface that can be accessed in a distributed environment. However, access to a Container should be limited to the ContainerManager that creates and manages it. A Container creates processes and manages their lifecycle. The container reports the status of processes it contains and performance statistics. These reports can be obtained directly from the interface or by registering callback objects called listeners.

Method Summary

ContainerProcess	createProcess(ComponentDescriptor componentDescriptor) This method creates a process inside the container based on the given ComponentDescriptor.
ContainerProcess	createProcess(ComponentDescriptor componentDescriptor, boolean restart, boolean mobile, java.lang.String commandLineParameters) This method creates a process inside the container based on the given ComponentDescriptor and lifecycle-related parameters.
ContainerProcess	createProcess(ComponentDescriptor componentDescriptor, UniqueID processID, ContainerProcessStatus processStatus, java.rmi.MarshalledObject processState) This method creates a process inside the container based on the given ComponentDescriptor, the process unique ID, and the saved process state.
java.net.InetAddress	getHost() This method returns the host on which this Container is running.
UniqueID	getID() This method returns a unique identifier for this Container.
PerformanceReport[]	getPerformanceReports() This method is used to obtain performance reports for the container.
ContainerProcess[]	getProcesses() This method is used to access all of the processes that are currently running inside a container.
ContainerProcessStatus[]	getStatusOfAllProcesses() This method is a convenience method that reports the status of all of the processes that are currently running inside a container.
void	registerContainerProcessListener(ContainerProcessListener listener) This method is used to register interest in receiving process status updates for every process in a container.
void	registerMobileProcessListener(MobileProcessListener listener) This method is used to register interest in receiving the serialized state of every process in the container that supports state serialization.
void	shutdown() This method is used to shutdown a container.
void	unregisterContainerProcessListener(ContainerProcessListener listener) This method is used to cancel interest in receiving process status updates for every process in a container.
void	unregisterMobileProcessListener(MobileProcessListener listener) This method is used to cancel interest in receiving the serialized state of processes in a container.

Method Detail

getID

public UniqueID getID()
               throws java.rmi.RemoteException

This method returns a unique identifier for this Container.

Returns:

unique identifier

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

getHost

public java.net.InetAddress getHost()
                             throws java.rmi.RemoteException

This method returns the host on which this Container is running.

Returns:

host

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

createProcess

public ContainerProcess createProcess(ComponentDescriptor componentDescriptor)
                               throws java.rmi.RemoteException,
                                      ProcessCreationException

This method creates a process inside the container based on the given ComponentDescriptor. This method returns an object that can be used to control the process. The process is not started until the ContainerProcess.start() method is called. Each call to createProcess() creates a unique process. A SecurityException is thrown if the container is unable to start the process.

Parameters:

componentDescriptor - descriptor for the process to be run

Returns:

an object implementing the ContainerProcess service interface.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

ProcessCreationException - if there is a problem creating the process in the container.

createProcess

public ContainerProcess createProcess(ComponentDescriptor componentDescriptor,
                                      UniqueID processID,
                                      ContainerProcessStatus processStatus,
                                      java.rmi.MarshalledObject processState)
                               throws java.rmi.RemoteException,
                                      ProcessCreationException

This method creates a process inside the container based on the given ComponentDescriptor, the process unique ID, and the saved process state. This variant of createProcess() is used to move an existing process into a new container. This method returns an object that can be used to control the process. The process is not started until the ContainerProcess.start() method is called. Each call to createProcess() creates a unique process. A SecurityException is thrown if the container is unable to start the process.

Parameters:

componentDescriptor - descriptor for the process to be inserted

processID - unique identifier for the process to be inserted

processStatus - last known status of process to be inserted

processState - serialized state of the process to be inserted

Returns:

an object implementing the ContainerProcess service interface.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

ProcessCreationException - if there is a problem creating the process in the container.

createProcess

public ContainerProcess createProcess(ComponentDescriptor componentDescriptor,
                                      boolean restart,
                                      boolean mobile,
                                      java.lang.String commandLineParameters)
                               throws java.rmi.RemoteException,
                                      ProcessCreationException

This method creates a process inside the container based on the given ComponentDescriptor and lifecycle-related parameters. This variant of createProcess() is used to override the default lifecycle-related parameters of the descriptor. This method returns an object that can be used to control the process. The process is not started until the ContainerProcess.start() method is called. Each call to createProcess() creates a unique process. A SecurityException is thrown if the container is unable to start the process.

Parameters:

componentDescriptor - descriptor for the process to be inserted

restart - boolean indicating whether this process should be restarted on failure.

mobile - boolean indicating whether this process can be moved between containers or platforms.

commandLineParameters - command line parameters to be passed to the process

Returns:

an object implementing the ContainerProcess service interface.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

ProcessCreationException - if there is a problem creating the process in the container.

getProcesses

public ContainerProcess[] getProcesses()
                                throws java.rmi.RemoteException

This method is used to access all of the processes that are currently running inside a container. This method returns an array of objects implementing the ContainerProcess interface that can be used to control the processes. The container is not required to return ContainerProcess objects for processes that have stopped, since these processes are obsolete. The container should return objects representing processes with the following states (defined in ContainerProcessStatus): CREATED, STARTED, and FAILED.

Returns:

array of objects implementing the ContainerProcess interface, or null if there are no processes running in the container

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

getStatusOfAllProcesses

public ContainerProcessStatus[] getStatusOfAllProcesses()
                                                 throws java.rmi.RemoteException

This method is a convenience method that reports the status of all of the processes that are currently running inside a container. This method returns an array of ContainerProcessStatus objects that represent the status of the processes inside the container. The container is not required to generate updated process status reports during execution of this method, only to report the most recent status report it has for each process. The container is not required to return ContainerProcessStatus objects for processes that have stopped, since these processes are obsolete.

Returns:

array of ContainerProcessStatus objects or null if there are no processes running in the container

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

getPerformanceReports

public PerformanceReport[] getPerformanceReports()
                                          throws java.rmi.RemoteException

This method is used to obtain performance reports for the container. This method returns an array of PerformanceReport objects that describe the current loading of the container. The first PerformanceReport in the array must be the memory loading (heap size) of the container, and subsequent reports are implementation-defined. The container is not required to generate updated performance reports during execution of this method, only to report the most recent performance statistics it has gathered.

Returns:

array of PerformanceReport objects

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

registerContainerProcessListener

public void registerContainerProcessListener(ContainerProcessListener listener)
                                      throws java.rmi.RemoteException

This method is used to register interest in receiving process status updates for every process in a container. The container implementation must call the appropriate method on the listener whenever the status of a process in the container changes.

Parameters:

listener - an object that implements the ContainerProcessListener interface or one of its subinterfaces, such as ContainerListener or ContainerManagerListener.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

unregisterContainerProcessListener

public void unregisterContainerProcessListener(ContainerProcessListener listener)
                                        throws java.rmi.RemoteException

This method is used to cancel interest in receiving process status updates for every process in a container. The container implementation should no longer call methods on the listener, but method calls that are already in progress will be completed.

Parameters:

listener - an object that implements the ContainerProcessListener interface or one of its subinterfaces, such as ContainerListener or ContainerManagerListener.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

registerMobileProcessListener

public void registerMobileProcessListener(MobileProcessListener listener)
                                   throws java.rmi.RemoteException

This method is used to register interest in receiving the serialized state of every process in the container that supports state serialization. The container implementation must call the appropriate method on the listener whenever the serialized state of a process in the container is updated.

Parameters:

listener - an object that implements the MobileProcessListener interface.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

unregisterMobileProcessListener

public void unregisterMobileProcessListener(MobileProcessListener listener)
                                     throws java.rmi.RemoteException

This method is used to cancel interest in receiving the serialized state of processes in a container. The container implementation should no longer call methods on the listener, but method calls that are already in progress will be completed.

Parameters:

listener - an object that implements the MobileProcessListener interface.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.

shutdown

public void shutdown()
              throws java.rmi.RemoteException

This method is used to shutdown a container. The container should stop all of its processes and exit gracefully.

Throws:

java.rmi.RemoteException - if there is an error communicating with the container.