org.objectweb.proactive.core.runtime
Interface ProActiveRuntime

All Superinterfaces:
Job, SecurityEntity
All Known Subinterfaces:
ProActiveRuntimeForwarder
All Known Implementing Classes:
ProActiveRuntimeAdapter, ProActiveRuntimeForwarderImpl, ProActiveRuntimeImpl

public interface ProActiveRuntime
extends Job, SecurityEntity

A ProActiveRuntime offers a set of services needed by ProActive to work with remote JVM. Each JVM that is aimed to hold active objects must contain one and only one instance of the ProActiveRuntime class. That instance, when created, will register itself to some registry where it is possible to perform a lookup (such as the RMI registry).

When ProActive needs to interact with a remote JVM, it will lookup for the ProActiveRuntime associated with that JVM (using typically the RMI Registry) and use the remote interface of the ProActiveRuntime to perform the interaction.

Aside the getter giving information about the VM, the 2 services offered are :

Since:
ProActive 0.91
Version:
1.0, 2002/08/29
Author:
ProActive Team

Field Summary
static org.apache.log4j.Logger runtimeLogger
           
 
Method Summary
 void addAcquaintance(java.lang.String proActiveRuntimeName)
          **For internal use only** Tells this runtime that it's registered in another one
 UniversalBody createBody(java.lang.String nodeName, ConstructorCall bodyConstructorCall, boolean isNodeLocal)
           This method is the basis for creating remote active objects.
 java.lang.String createLocalNode(java.lang.String nodeName, boolean replacePreviousBinding, ProActiveSecurityManager nodeSecurityManager, java.lang.String vnName, java.lang.String jobId)
          Creates a new Node in the same VM as this ProActiveRuntime
 void createVM(UniversalProcess remoteProcess)
          Creates a new ProActiveRuntime associated with a new VM on the host defined in the given process.
 java.lang.String[] getAcquaintances()
          Returns all the ProActiveRuntime URL in which this runtime is registered
 java.util.ArrayList getActiveObjects(java.lang.String nodeName)
          Returns all Active Objects deployed on the node with the given name on this ProActiveRuntime
 java.util.ArrayList getActiveObjects(java.lang.String nodeName, java.lang.String className)
          Returns all Active Objects with the specified class name, deployed on the node with the given name on this ProActiveRuntime
 byte[] getClassDataFromParentRuntime(java.lang.String className)
          Looks for class bytecode in the ancestors of the current runtime : first it tries in the father runtime, then in the grand-father etc...
 byte[] getClassDataFromThisRuntime(java.lang.String className)
          Looks for class bytecode in the current runtime.
 ProActiveDescriptor getDescriptor(java.lang.String url, boolean isHierarchicalSearch)
          return the pad matching with the given url or parse it from the file system
 java.lang.String getJobID(java.lang.String nodeUrl)
           
 java.lang.String[] getLocalNodeNames()
          Returns the name of all nodes known by this ProActiveRuntime on this VM
 ProActiveRuntime getProActiveRuntime(java.lang.String proActiveRuntimeName)
          Returns the ProActiveRuntime of specified name
 ProActiveRuntime[] getProActiveRuntimes()
          Returns all the ProActiveRuntime registered on this ProActiveRuntime on this VM
 ExternalProcess getProcessToDeploy(ProActiveRuntime proActiveRuntimeDist, java.lang.String creatorID, java.lang.String vmName, java.lang.String padURL)
          Ask proActiveRuntimeDist for the process with given ids: padURL, creatorID, vmName.
 java.lang.String getURL()
          Returns the url of this ProActiveRuntime on the local or remote VM
 VirtualNode getVirtualNode(java.lang.String virtualNodeName)
          Returns the VirtualNode with the given name
 VMInformation getVMInformation()
          Returns the JVM information as one object.
 java.lang.String getVNName(java.lang.String Nodename)
           
 void killAllNodes()
          Kills all Nodes in this ProActiveRuntime
 void killNode(java.lang.String nodeName)
          Kills the Node of the given name and all Active Objects deployed on it.
 void killRT(boolean softly)
          Kills this ProActiveRuntime and this VM
 void launchMain(java.lang.String className, java.lang.String[] parameters)
          launch the main method of the main class with parameters
 void newRemote(java.lang.String className)
          construct a new instance remotly
 UniversalBody receiveBody(java.lang.String nodeName, Body body)
           This method is the basis for migrating active objects.
 UniversalBody receiveCheckpoint(java.lang.String nodeName, Checkpoint ckpt, int inc)
          The runtime recovers the body contained in the checkpoint ckpt.
 void register(ProActiveRuntime proActiveRuntimeDist, java.lang.String proActiveRuntimeUrl, java.lang.String creatorID, java.lang.String creationProtocol, java.lang.String vmName)
          **For internal use only** Allows this ProActiveRuntime on this VM to register another ProActiveRuntime
 void registerVirtualNode(java.lang.String virtualNodeName, boolean replacePreviousBinding)
          Registers the virtualNode of the given name in a registry such RMIRegistry or Jini Service Lookup
 void rmAcquaintance(java.lang.String proActiveRuntimeName)
          **For internal use only** .
 void unregister(ProActiveRuntime proActiveRuntimeDist, java.lang.String proActiveRuntimeUrl, java.lang.String creatorID, java.lang.String creationProtocol, java.lang.String vmName)
          **For internal use only** Allows this ProactiveRuntime on this VM to unregister an already resigesterd ProActiveRuntime.
 void unregisterAllVirtualNodes()
          Unregisters all VirtualNodes from the local runtime
 void unregisterVirtualNode(java.lang.String virtualNodeName)
          Unregisters the VirtualNode of the given name from the local runtime.
 
Methods inherited from interface org.objectweb.proactive.Job
getJobID
 
Methods inherited from interface org.objectweb.proactive.ext.security.SecurityEntity
getCertificate, getCertificateEncoded, getEntities, getPolicy, getPublicKey, publicKeyExchange, randomValue, secretKeyExchange, startNewSession, terminateSession
 

Field Detail

runtimeLogger

public static final org.apache.log4j.Logger runtimeLogger
Method Detail

createLocalNode

public java.lang.String createLocalNode(java.lang.String nodeName,
                                        boolean replacePreviousBinding,
                                        ProActiveSecurityManager nodeSecurityManager,
                                        java.lang.String vnName,
                                        java.lang.String jobId)
                                 throws NodeException
Creates a new Node in the same VM as this ProActiveRuntime

Parameters:
nodeName - the name of the node to create localy
replacePreviousBinding -
Returns:
the url of the newly created node in the target VM
Throws:
NodeException - if the new node cannot be created

killAllNodes

public void killAllNodes()
                  throws ProActiveException
Kills all Nodes in this ProActiveRuntime

Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

killNode

public void killNode(java.lang.String nodeName)
              throws ProActiveException
Kills the Node of the given name and all Active Objects deployed on it.

Parameters:
nodeName - the name of the node to kill
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

createVM

public void createVM(UniversalProcess remoteProcess)
              throws java.io.IOException,
                     ProActiveException
Creates a new ProActiveRuntime associated with a new VM on the host defined in the given process.

Parameters:
remoteProcess - the process that will originate the creation of the runtime
Throws:
java.io.IOException - if the new VM cannot be created
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getLocalNodeNames

public java.lang.String[] getLocalNodeNames()
                                     throws ProActiveException
Returns the name of all nodes known by this ProActiveRuntime on this VM

Returns:
the name of all nodes known by this ProActiveRuntime on this VM
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getVMInformation

public VMInformation getVMInformation()
Returns the JVM information as one object. This method allows to retrieve all JVM information in one call to optimize performance.

Returns:
the JVM information as one object

register

public void register(ProActiveRuntime proActiveRuntimeDist,
                     java.lang.String proActiveRuntimeUrl,
                     java.lang.String creatorID,
                     java.lang.String creationProtocol,
                     java.lang.String vmName)
              throws ProActiveException
**For internal use only** Allows this ProActiveRuntime on this VM to register another ProActiveRuntime

Parameters:
proActiveRuntimeDist - the remote ProactiveRuntime to register
proActiveRuntimeUrl - the url of the remote ProActiveRuntime
creatorID - the name of the creator of the remote ProActiveRuntime
creationProtocol - the protocol used to register the remote ProActiveRuntime when created
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

unregister

public void unregister(ProActiveRuntime proActiveRuntimeDist,
                       java.lang.String proActiveRuntimeUrl,
                       java.lang.String creatorID,
                       java.lang.String creationProtocol,
                       java.lang.String vmName)
                throws ProActiveException
**For internal use only** Allows this ProactiveRuntime on this VM to unregister an already resigesterd ProActiveRuntime.

Parameters:
proActiveRuntimeDist - the remote ProactiveRuntime to unregister.
proActiveRuntimeUrl - the url of the remote ProActiveRuntime
creatorID - the name of the creator of the remote ProActiveRuntime
creationProtocol - the protocol used to register the remote ProActiveRuntime when created
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getProActiveRuntimes

public ProActiveRuntime[] getProActiveRuntimes()
                                        throws ProActiveException
Returns all the ProActiveRuntime registered on this ProActiveRuntime on this VM

Returns:
all the ProActiveRuntime registered on this ProActiveRuntime on this VM
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getProActiveRuntime

public ProActiveRuntime getProActiveRuntime(java.lang.String proActiveRuntimeName)
                                     throws ProActiveException
Returns the ProActiveRuntime of specified name

Parameters:
proActiveRuntimeName - the name of the ProActiveruntime to return
Returns:
the ProActiveRuntime of specified name
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

addAcquaintance

public void addAcquaintance(java.lang.String proActiveRuntimeName)
                     throws ProActiveException
**For internal use only** Tells this runtime that it's registered in another one

Parameters:
proActiveRuntimeName - the name of the remote ProActiveRuntime in which this runtime is registered
Throws:
ProActiveException

getAcquaintances

public java.lang.String[] getAcquaintances()
                                    throws ProActiveException
Returns all the ProActiveRuntime URL in which this runtime is registered

Returns:
all the ProActiveRuntime URL in which this runtime is registered
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

rmAcquaintance

public void rmAcquaintance(java.lang.String proActiveRuntimeName)
                    throws ProActiveException
**For internal use only** . Tell to this runtime that is no more registered in proActiveRuntimeName.

Parameters:
proActiveRuntimeName - the name of the remote ProActiveRuntime.
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

killRT

public void killRT(boolean softly)
            throws java.lang.Exception
Kills this ProActiveRuntime and this VM

Parameters:
softly - if false, this Runtime is killed abruptely if true, if that runtime originates the creation of a rmi registry, it waits until the registry is empty before dying. To be more precise a thread is created to ask periodically the registry if objects are still registered.
Throws:
java.lang.Exception - if a problem occurs when killing this ProActiveRuntime

getURL

public java.lang.String getURL()
Returns the url of this ProActiveRuntime on the local or remote VM


getActiveObjects

public java.util.ArrayList getActiveObjects(java.lang.String nodeName)
                                     throws ProActiveException
Returns all Active Objects deployed on the node with the given name on this ProActiveRuntime

Parameters:
nodeName - the name of the node
Returns:
ArrayList of ArrayList. The latter contains [body, classname].
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getActiveObjects

public java.util.ArrayList getActiveObjects(java.lang.String nodeName,
                                            java.lang.String className)
                                     throws ProActiveException
Returns all Active Objects with the specified class name, deployed on the node with the given name on this ProActiveRuntime

Parameters:
nodeName - the name of the node
className - class of the Active Objects to look for
Returns:
Active Objects of the specified class name deployed on this ProactiveRuntime
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getVirtualNode

public VirtualNode getVirtualNode(java.lang.String virtualNodeName)
                           throws ProActiveException
Returns the VirtualNode with the given name

Parameters:
virtualNodeName - the name of the VirtualNode to be acquired
Returns:
VirtualNode the virtualnode of the given name or null if such virtualNode does not exist, or has not been yet activated.
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

registerVirtualNode

public void registerVirtualNode(java.lang.String virtualNodeName,
                                boolean replacePreviousBinding)
                         throws ProActiveException
Registers the virtualNode of the given name in a registry such RMIRegistry or Jini Service Lookup

Parameters:
virtualNodeName -
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

unregisterVirtualNode

public void unregisterVirtualNode(java.lang.String virtualNodeName)
                           throws ProActiveException
Unregisters the VirtualNode of the given name from the local runtime.

Parameters:
virtualNodeName - the virtualNode to unregister.
Throws:
ProActiveException - if a problem occurs when trying to unregister the virtualNode

unregisterAllVirtualNodes

public void unregisterAllVirtualNodes()
                               throws ProActiveException
Unregisters all VirtualNodes from the local runtime

Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getJobID

public java.lang.String getJobID(java.lang.String nodeUrl)
                          throws ProActiveException
Parameters:
nodeUrl -
Returns:
the jobId of the node with the given name
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

createBody

public UniversalBody createBody(java.lang.String nodeName,
                                ConstructorCall bodyConstructorCall,
                                boolean isNodeLocal)
                         throws ProActiveException,
                                ConstructorCallExecutionFailedException,
                                java.lang.reflect.InvocationTargetException

This method is the basis for creating remote active objects. It receives a ConstructorCall that is the constructor call of the body of the active object to create. Inside the parameters of this constructor call is the constructor call of the reified object. Upon execution of the constructor call of the body, the body holding a reference on the reified object will get created and returned.

The method returns a reference on the RMI stub of the newly created body.

Parameters:
nodeName - the name of the node the newly created active object will be associated to
bodyConstructorCall - the Constructor call allowing to create the body
isNodeLocal - boolean. True if proxy and body are on the same vm, false otherwise
Returns:
a stub on the newly created body.
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProactiveRuntime
ConstructorCallExecutionFailedException - if the constructor call cannot be executed
java.lang.reflect.InvocationTargetException - if the java constructor execution failed

receiveBody

public UniversalBody receiveBody(java.lang.String nodeName,
                                 Body body)
                          throws ProActiveException

This method is the basis for migrating active objects. It receives a Body that embbeds the reified object and its graph of passive objects. Once transfered remotely using serialization, the body should restart itself and perform all updates needed to be functionning.

The method returns a reference on the RMI stub of the migrated body.

Parameters:
nodeName - the name of the node the newly created active object will be associated to
body - the body of the active object migrating to this node.
Returns:
a RMI stub on the migrated body.
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

receiveCheckpoint

public UniversalBody receiveCheckpoint(java.lang.String nodeName,
                                       Checkpoint ckpt,
                                       int inc)
                                throws ProActiveException
The runtime recovers the body contained in the checkpoint ckpt.

Parameters:
nodeName - node on which the body is restarted
ckpt - checkpoint to use for recovery
inc - incarnation number of this recovery
Returns:
*not used*
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getProcessToDeploy

public ExternalProcess getProcessToDeploy(ProActiveRuntime proActiveRuntimeDist,
                                          java.lang.String creatorID,
                                          java.lang.String vmName,
                                          java.lang.String padURL)
                                   throws ProActiveException
Ask proActiveRuntimeDist for the process with given ids: padURL, creatorID, vmName. Used for hierarchical deployment.

Parameters:
proActiveRuntimeDist -
creatorID -
vmName -
padURL -
Returns:
the process with given ids: padURL, creatorID, vmName
Throws:
ProActiveException

getVNName

public java.lang.String getVNName(java.lang.String Nodename)
                           throws ProActiveException
Throws:
ProActiveException

getClassDataFromThisRuntime

public byte[] getClassDataFromThisRuntime(java.lang.String className)
                                   throws ProActiveException
Looks for class bytecode in the current runtime. If current runtime has no father, stub generation can be intented to get the class bytecode

Parameters:
className - name of the class
Returns:
the bytecode corresponding to the given class, or null if not found
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

getClassDataFromParentRuntime

public byte[] getClassDataFromParentRuntime(java.lang.String className)
                                     throws ProActiveException
Looks for class bytecode in the ancestors of the current runtime : first it tries in the father runtime, then in the grand-father etc...

Parameters:
className - name of the class
Returns:
the bytecode corresponding to the given class, or null if not found
Throws:
ProActiveException - if a problem occurs due to the remote nature of this ProActiveRuntime

launchMain

public void launchMain(java.lang.String className,
                       java.lang.String[] parameters)
                throws java.lang.ClassNotFoundException,
                       java.lang.NoSuchMethodException,
                       ProActiveException
launch the main method of the main class with parameters

Parameters:
className -
parameters -
Throws:
java.lang.ClassNotFoundException
java.lang.NoSuchMethodException
ProActiveException

newRemote

public void newRemote(java.lang.String className)
               throws java.lang.ClassNotFoundException,
                      ProActiveException
construct a new instance remotly

Parameters:
className - class to instance
Throws:
java.lang.ClassNotFoundException
ProActiveException

getDescriptor

public ProActiveDescriptor getDescriptor(java.lang.String url,
                                         boolean isHierarchicalSearch)
                                  throws java.io.IOException,
                                         ProActiveException
return the pad matching with the given url or parse it from the file system

Parameters:
url - url of the pad
isHierarchicalSearch - if yes search for the pad hierarchically
Returns:
the pad found or a new pad parsed from xmlDescriptorUrl
Throws:
ProActiveException
java.io.IOException


Copyright 2001-2005 INRIA All Rights Reserved.