one.world Documentation: Class Environment

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

one.world.core
Class Environment

java.lang.Object
  |
  +--one.world.core.Component
        |
        +--one.world.core.Environment

All Implemented Interfaces:: Serializable

public final class Environment
extends Component

Implementation of an environment. Environments are containers for stored tuples, active computations, and other environments, thus providing a hierarchical structuring for one.world. Furthermore, environments are associated with concurrency domains, which provide the animators for their computations, and protection domains, which determine isolation boundaries. Each environment has its own concurrency domain. Each environment either has its own protection domain or inherits the parent environment's protection domain.

Environments as Components

Environments are components, albeit privileged ones. They expose three handlers for linking, an imported main handler, an exported request handler, and an imported monitor handler. The main handler notifies an environment's main component of state changes, such as when the environment is activated or terminated. The request handler accepts arbitrary events, but is typically used for requesting operations on environments, operations to bind a resource, or operations to load code. The monitor handler lets an environment monitor the requests issued by descendant environments.

Requests issued to an environment's request handler are delivered to the first ancestral environment whose monitor handler is linked. The root environment is guaranteed to have a default request manager linked to its monitor handler. This request manager understands requests on environments, binding requests for communication channels as well as local tuple storage, and code loading requests.

Events issued to an environment's request handler are annotated with the ID of the requesting environment. This ID is accessible through the event's meta-data, using the Constants.REQUESTOR_ID field. If this ID is already defined, an environment's request handler ensures that it identifies either the requesting environment or one of its descendants and otherwise signals an exceptional event to the source of the request.

Components control environments through environment events as well as accept, create, load, move, rename, and restore requests. The corresponding events are defined in the one.world.env package. The operations on environments are:

create to create a new child environment,
load to load code into an environment,
activate to activate an environment,
check-point to check-point the current state of an environment and all its descendants,
restore to restore environments to a previously check-pointed state,
move to move an environment and all its descendants, which optionally clones the environment(s) as well,
rename to rename an environment,
terminate to terminate the computation in an environment,
unload to unload code from an environment,
destroy to destroy an environment and all its descendants.

Environment States

Environments can be in one of the following states.

In the INACTIVE state, an environment has been created, can be linked and can store tuples, but does not execute computations.
In the ACTIVE state, an environment, in addition to storing tuples, is also executing a computation.
In the TERMINATING state, an environment is currently terminating, that is, going back from the active to the inactive state.
In the DESTROYING state, an environment is currently being destroyed.
In the DESTROYED state, an environment has been destroyed. A destroyed environment does not execute computations nor store tuples.

Remarks

Invoking most of the methods implemented by this class requires the system permission to manage environments. The following methods can be safely called by applications in one.world.

When requesting to perform an operation on an environment, that operation may fail with an illegal state exception signalling that the environment is currently being modified. This exception means that another operation on the same environment is currently under way, which affects the state of that environment. Examples include the environment transitioning from the active to the inactive state, the environment being loaded into, being renamed, or being restored from a saved check-point. We chose to expose concurrent operations on the same environment, because this implementation choice has enabled a larger overall degree of concurrent environment operations.

Note that the root environment is always active after the system has started up. The root environment cannot be loaded into, renamed, moved, check-pointed, terminated, unloaded, or destroyed. Also note that events passed between components in different environments cannot reference any components, including environments.

Version:: $Revision: 1.100 $
See Also:: EnvironmentEvent, AcceptRequest, CreateRequest, LoadRequest, RenameRequest, RestoreRequest, MoveRequest, SystemPermission, Serialized Form

Inner Class Summary

static class Environment.Descriptor
          Implementation of an environment descriptor.

Inner classes inherited from class one.world.core.Component

Component.HandlerReference, Component.Importer

Field Summary

static int ACTIVE
          The status code for an active environment.

static int DESTROYED
          The status code for a destroyed environment.

static int DESTROYING
          The status code for an environment that is being destroyed.

static int INACTIVE
          The status code for an inactive environment.

static int TERMINATING
          The status code for a terminating environment.

Method Summary

static void activate(Guid requestorId, Guid envId)
          Activate the specified environment.

static long checkPoint(Guid requestorId, Guid envId)
          Check-point the specified environment and all its descendants.

static void copy(Guid requestorId, Guid envId, Guid newParentId)
          Copy the specified environment to the specified new parent.

static Environment create(Guid requestorId, Guid parentId, String name, boolean inherit)
          Create a new child environment.

static Environment create(Guid requestorId, Guid parentId, String name, boolean inherit, String init, Object closure)
          Create a new child environment.

static NestedConcurrencyDomain createNestedConcurrency(String service)
          Create a new, nested concurrency domain.

static boolean destroy(Guid requestorId, Guid envId)
          Destroy the specified environment and all its descendants.

static void ensureName(String name)
          Ensure that the specified name is a legal environment name.

static void ensurePermission()
          Ensure that the caller has the permission to manage environments.

Environment getChild(String name)
          Get the child environment witht the specified name.

List getChildren()
          Get the names of all child environments.

ConcurrencyDomain getConcurrencyDomain()
          Get the concurrency domain for this environment.

ComponentDescriptor getDescriptor()
          Get the component descriptor for this environment.

Guid getId()
          Get the ID for this environment.

Component.Importer getMain()
          Get the main imported event handler for this environment.

Component.Importer getMonitor()
          Get the monitor imported event handler for this environment.

String getName()
          Get the name for this environment.

Environment getParent()
          Get the parent environment for this environment.

Guid getParentId()
          Get the ID of the parent environment for this environment.

String getParentName()
          Get the name of the parent environment for this environment.

ProtectionDomain getProtectionDomain()
          Get the protection domain for this environment.

EventHandler getRequest()
          Get the request exported event handler for this environment.

static Environment getRoot()
          Get the root environment.

int getStatus()
          Get the current status for this environment.

Timer getTimer1()
          Get the timer for this environment.

static void load(Guid requestorId, Guid envId, String init, Object closure)
          Load the specified initializer and execute it within the specified environment.

static Environment lookup(Guid id)
          Look up the environment with the specified ID.

Environment lookupLocally(Guid id)
          Locally look up the environment with the specified ID.

static boolean move(Guid requestorId, Guid envId, Guid newParentId)
          Move the specified environment to the specified new parent.

static void moveAway(Guid requestorId, EventHandler resultHandler, Object resultClosure, Guid envId, String remoteHost, int remotePort, String remotePath, boolean clone)
          Move the specified environment to the new parent environment with the specified path on the specified remote host.

static void rename(Guid requestorId, Guid envId, String name)
          Rename the specified environment to the specified name.

static Environment resolve(Guid requestorId, Guid localRootId, String[] path)
          Resolve the specified local root and path.

static boolean restore(Guid requestorId, Guid envId, long timestamp)
          Restore the specified environment and all its descendants from the specified check-point.

static void shutDown()
          Shut down all environments.

static void startUp()
          Start up the environment hierarchy.

static void terminate(Guid requestorId, Guid envId)
          Terminate the specified environment.

String toString()
          Get a string representation for this environment.

static void unload(Guid requestorId, Guid envId)
          Unload the code from the protection domain rooted at the specified environment.

static EventHandler wrapForNested(EventHandler handler, NestedConcurrencyDomain concurrency)
          Wrap the specified event handler as a wrapped handler for the specified nested concurrency domain.

Methods inherited from class one.world.core.Component

declareExported, declareImported, equals, eventHandlers, getDescriptor, getEnvironment, getLinkedHandlers, getLinkedNumber, getTimer, hasEventHandler, hashCode, isFullyLinked, isLinked, isSealed, link, link, run, seal, unbox, undeclare, unlink, wrap

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INACTIVE

public static final int INACTIVE

The status code for an inactive environment. An inactive environment can store tuples and is ready for linking, but does not execute any computations.

ACTIVE

public static final int ACTIVE

The status code for an active environment. An active environment is actively executing code. Its main event handler must be linked against some component.

TERMINATING

public static final int TERMINATING

The status code for a terminating environment. A terminating environment is transitioning from the active back to the inactive state. In the terminating state, the environment is giving its main imported event handler time to react to the pending termination.

DESTROYING

public static final int DESTROYING

The status code for an environment that is being destroyed. Such an environment is transitioning from the inactive or the active to the destroyed state. If the environment was in the active state before entering the destroying state, it is giving its main imported event handler time to react to the pending destruction.

DESTROYED

public static final int DESTROYED

The status code for a destroyed environment. A destroyed environment has terminated all activity, deleted all stored tuples, and is ready for reclamation by the garbage collector.

Method Detail

getDescriptor

public ComponentDescriptor getDescriptor()

Get the component descriptor for this environment.

Overrides:: getDescriptor in class Component

Following copied from class: one.world.core.Component

Returns:: The component descriptor for this component.

getMain

public Component.Importer getMain()

Get the main imported event handler for this environment.

Returns:: The main imported event handler.
Throws:: SecurityException - Signals that the caller does not have permission to manage environments.

getRequest

public EventHandler getRequest()

Get the request exported event handler for this environment.

Returns:: The request exported event handler.
Throws:: SecurityException - Signals that the caller does not have permission to manage environments.

getMonitor

public Component.Importer getMonitor()

Get the monitor imported event handler for this environment.

Returns:: The monitor imported event handler.
Throws:: SecurityException - Signals that the caller does not have permission to manage environments.

getTimer1

public Timer getTimer1()

Get the timer for this environment.

Returns:: The timer for this environment.
Throws:: SecurityException - Signals that the caller does not have permission to manage environments.
See Also:: Component.getTimer()

getId

public Guid getId()

Get the ID for this environment.

Returns:: The ID for this environment.

getName

public String getName()

Get the name for this environment.

Returns:: The name for this environment.

getConcurrencyDomain

public ConcurrencyDomain getConcurrencyDomain()

Get the concurrency domain for this environment.

If an application retains a reference to the object returned by this method, it must refresh that reference whenever a code loading operation has failed, the environment has been restored from a saved check-point or the environment's code has been unloaded.

Returns:: The concurrency domain for this environment.
See Also:: create(Guid,Guid,String,boolean,String,Object), load(one.util.Guid, one.util.Guid, java.lang.String, java.lang.Object), restore(one.util.Guid, one.util.Guid, long), unload(one.util.Guid, one.util.Guid)

getProtectionDomain

public ProtectionDomain getProtectionDomain()

Get the protection domain for this environment.

If an application retains a reference to the object returned by this method, it must refresh that reference whenever the environment's code has been unloaded.

Returns:: The protection domain for this environment.
See Also:: unload(one.util.Guid, one.util.Guid)

getParent

public Environment getParent()

Get the parent environment for this environment.

Returns:: The parent environment for this environment or null if this environment is the root environment.
Throws:: IllegalStateException - Signals that this environment is either being destroyed or has been destroyed, or that the system is not running.; SecurityException - Signals that the caller does not have permission to manage environments.

getParentId

public Guid getParentId()

Get the ID of the parent environment for this environment.

Returns:: The ID of the parent environment for this environment or null if this environment is the root environment.
Throws:: IllegalStateException - Signals that this environment is either being destroyed or has been destroyed, or that the system is not running.

getParentName

public String getParentName()

Get the name of the parent environment for this environment.

Returns:: The name of the parent environment for this environment or null if this environment is the root environment.
Throws:: IllegalStateException - Signals that this environment is either being destroyed or has been destroyed, or that the system is not running.

getChild

public Environment getChild(String name)

Get the child environment witht the specified name.

Parameters:: name - The name of the child environment to look up.
Returns:: The child environment with the specified name or null if this environment has no such child.
Throws:: IllegalStateException - Signals that this environment is either being destroyed or has been destroyed, or that the system is not running.

getChildren

public List getChildren()

Get the names of all child environments.

Returns:: A list with the names of all child environments.
Throws:: IllegalStateException - Signals that this environment is either being destroyed or has been destroyed, or that the system is not running.

toString

public String toString()

Get a string representation for this environment.

Overrides:: toString in class Object

getRoot

public static Environment getRoot()

Get the root environment. The root environment represents the root of the environment hierarchy running on a node. It provides the environment for trusted services and cannot accommodate any other components.

Returns:: The root environment.
Throws:: SecurityException - Signals that the caller does not have permission to manage environments.

create

public static Environment create(Guid requestorId,
                                 Guid parentId,
                                 String name,
                                 boolean inherit)
                          throws IOException

Create a new child environment. The newly created child environment is a child of the specified parent environment and has the specified name.

Parameters:: requestorId - The ID of the environment requesting this operation.; parentId - The ID of the parent environment.; name - The name of the new child environment.; inherit - The flag for whether to inherit the parent environment's protection domain.
Returns:: The new environment.
Throws:: NullPointerException - Signals that parentId or name is null.; IllegalArgumentException - Signals that no environment with the specified ID exists, that name is an illegal name for an environment, or that the specified parent environment already has a child with the specified name.; IOException - Signals an exceptional condition when writing the persistent environment state for the new environment.; IllegalStateException - Signals that the system is not running.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified parent environment is not a descendant of the specified requesting environment.

create

public static Environment create(Guid requestorId,
                                 Guid parentId,
                                 String name,
                                 boolean inherit,
                                 String init,
                                 Object closure)
                          throws IOException,
                                 ClassNotFoundException,
                                 NoSuchMethodException,
                                 InvocationTargetException

Create a new child environment. The newly created child environment is a child of the specified parent environment and has the specified name.

If init is not null, it is treated as the name of the class providing the initializer for the new environment. The initializer has the signature public static void init(Environment, Object). It is invoked after the new child environment has been created and is passed a reference to the child environment as well as the specified closure.

Note that the initializer may throw any Throwable. If the initializer terminates exceptionally, all event handlers for this environment are automatically unlinked, thus ensuring that objects created by the initializer and linking operations performed by the initializer do not persist. However, error recovery does not recreate the class loader for the environment, which requires an explicit unload operation.

Parameters:: requestorId - The ID of the environment requesting this operation.; parentId - The ID of the parent environment.; name - The name of the new child environment.; inherit - The flag for whether to inherit the parent environment's protection domain.; init - The name of the class providing the initializer for the new child environment, or null if no initialization is to be performed.; closure - The closure for the initializer.
Returns:: The new environment.
Throws:: NullPointerException - Signals that parentId or name is null.; IllegalArgumentException - Signals that no environment with the specified ID exists, that name is an illegal name for an environment, or that the specified parent environment already has a child with the specified name.; IOException - Signals an exceptional condition when writing the persistent environment state for the new environment.; ClassNotFoundException - Signals that the class with name init cannot be found.; NoSuchMethodException - Signals that the class with name init does not have an appropriate init() method.; InvocationTargetException - Signals an exceptional condition while executing the initializer.; IllegalStateException - Signals that the system is not running or that the specified parent environment is currently being modified.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified parent environment is not a descendant of the specified requesting environment.

load

public static void load(Guid requestorId,
                        Guid envId,
                        String init,
                        Object closure)
                 throws ClassNotFoundException,
                        NoSuchMethodException,
                        InvocationTargetException

Load the specified initializer and execute it within the specified environment. This method loads the specified class and invokes its

public static void init(Environment,
 Object)

method on the specified environment and closure.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to execute the initializer in.; init - The name of the class providing the initializer.; closure - The closure for the initializer.
Throws:: ClassNotFoundException - Signals that the class with name init cannot be found.; NoSuchMethodException - Signals that the class with name init does not have an appropriate init() method.; InvocationTargetException - Signals an exceptional condition while executing the initializer.; IllegalStateException - Signals that the system is not running, that the specified environment is already active, that it is currently being modified, or that it's main event handler has already been linked.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified parent environment is not a descendant of the specified requesting environment.

lookup

public static Environment lookup(Guid id)

Look up the environment with the specified ID.

Parameters:: id - The ID of the environment to look up.
Returns:: The correspoding environment.
Throws:: NullPointerException - Signals that id is null.; IllegalArgumentException - Signals that no environment with the specified ID exists.; IllegalStateException - Signals that the system is not running.; SecurityException - Signals that the caller does not have permission to manage environments.

lookupLocally

public Environment lookupLocally(Guid id)

Locally look up the environment with the specified ID. This method looks up the environment with the specified ID in the subtree of the environment hierarchy that is rooted at this environment.

Parameters:: id - The ID of the environment to look up.
Returns:: The correspoding environment.
Throws:: NullPointerException - Signals that id is null.; IllegalArgumentException - Signals that no environment with the specified ID exists locally.; IllegalStateException - Signals that the system is not running.

resolve

public static Environment resolve(Guid requestorId,
                                  Guid localRootId,
                                  String[] path)
                           throws UnknownResourceException

Resolve the specified local root and path. The specified local root and path specify either an absolute path, a relative path, or an ID-relative path, and correspond to the ident and path fields of a structured I/O resource descriptor.

This method assumes that the specified path has been normalized. In other words, path segments other than "." and ".." as well as a leading "/" segment are always treated as names of child environments. Furthermore, this method assumes that the specified local root and path have been validate. It signals an illegal argument exception if they are not well-formed.

Parameters:: requestorId - The ID of the environment requesting this operation.; localRootId - The ID of the local root for ID-relative paths.; path - The path.
Returns:: The corresponding environment.
Throws:: NullPointerException - Signals that both localRootId and path are null, or that an entry in path is null.; IllegalArgumentException - Signals that the specified requesting environment does not exist, or that the specified local root and path are not valid.; UnknownResourceException - Signals that the specified local root and path describe a non-existent environment.; IllegalStateException - Signals that the system is not running.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified local root and path specify an environment which is not a descendant of the requesting environment.
See Also:: SioResource

rename

public static void rename(Guid requestorId,
                          Guid envId,
                          String name)

Rename the specified environment to the specified name.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to be renamed.; name - The new name.
Throws:: NullPointerException - Signals that envId or name is null.; IllegalArgumentException - Signals that no environment with the specified ID exists, that name is an illegal name for an environment, or that the environment's parent already has a child with the specified name.; IllegalStateException - Signals that the system is not running or that the specified environment is being modified.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified environment is not a descendant of the specified requesting environment.

move

public static boolean move(Guid requestorId,
                           Guid envId,
                           Guid newParentId)
                    throws IOException,
                           InvalidTupleException,
                           ClassNotFoundException

Move the specified environment to the specified new parent. This method moves the specified environment and all its descendants to the specified new parent. To move active environments, this method uses a check-point.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to move.; newParentId - The ID of the new parent environment.
Returns:: true if the requesting environment has been moved.
Throws:: NullPointerException - Signals that envId or newParentId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists, that the new parent already has a child with the same name as the environment to be moved, or that the environment to be moved is the root environment.; IOException - Signals an exceptional condition when creating the check-point for the environments to be moved.; InvalidTupleException - Signals an exceptional condition while restoring the check-point for the moved environment(s).; ClassNotFoundException - Signals that a class was not found while restoring the check-point for the moved environment(s).; IllegalStateException - Signals that the system is not running, or that one of the specified environments is currently being modified.; SecurityException - Signals that the caller does not have permission to manage environments, or that either the environment to be moved or the new parent environment is not a descendant of the specified requesting environment.

copy

public static void copy(Guid requestorId,
                        Guid envId,
                        Guid newParentId)
                 throws IOException,
                        InvalidTupleException,
                        ClassNotFoundException

Copy the specified environment to the specified new parent. This method copies the specified environment and all its descendants to the specified new parent. To copy active environments, this method uses a modified check-point of the original environment(s).

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to copy.; newParentId - The ID of the new parent environment.
Throws:: NullPointerException - Signals that envId or newParentId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists, that the new parent already has a child with the same name as the environment to be copied, or that the environment to be copied is the root environment.; IOException - Signals an exceptional condition when creating the check-point for the environments to be copied or when copying the persistent environment state.; InvalidTupleException - Signals an exceptional condition while restoring the check-point for the copied environment(s).; ClassNotFoundException - Signals that a class was not found while restoring the check-point for the copied environment(s).; IllegalStateException - Signals that the system is not running, or that one of the specified environments is currently being modified.; SecurityException - Signals that the caller does not have permission to manage environments, or that either the environment to be copied or the new parent environment is not a descendant of the specified requesting environment.

moveAway

public static void moveAway(Guid requestorId,
                            EventHandler resultHandler,
                            Object resultClosure,
                            Guid envId,
                            String remoteHost,
                            int remotePort,
                            String remotePath,
                            boolean clone)

Move the specified environment to the new parent environment with the specified path on the specified remote host. This method remotely moves, or copies if clone is true, the specified environment to the specified new parent environment.

When this method returns, the move is not complete. Rather, the move operation continues asynchronously and the specified result handler is notified upon completion, be it normal or exceptional. Note, however, that the result handler is not notified of a successful move (but not copy) operation if the requesting environment has been moved itself.

The following exceptional conditions may be signalled to the specified result handler:

IllegalArgumentException: Signals that no environment with the specified ID exists, that the specified environment is the root environment, that the specified environment represents a partial protection domain, or that the new parent already has a child with the same name as the environment to be moved.
UnknownResourceException: Signals that no such remote host or remote environment exists.
IOException: Signals an exceptional condition while moving the persistent environment state.
TupleException: Signals an exceptional condition while restoring the check-point for the moved environments.
ClassNotFoundException: Signals that a class was not found while restoring the check-point for the moved environments.
IllegalStateException: Signals that the system is not running (or being shut down while the move is in progress), or that one of the specified environments is currently being modified.

Note that using this method to move an environment and its descendants to some location on the same node will always fail, because the environment IDs are already taken (by the original environments). Local moves must be performed with the move method.

Parameters:: requestorId - The ID of the environment requesting this operation.; resultHandler - The result handler.; resultClosure - The closure for the event delivered to the result handler.; envId - The ID of the environment to move.; remoteHost - The host to move the environment to.; remotePort - The port on which the remote node is exporting the REP event handler for moving environments, or -1 if the default REP port is to be used.; remotePath - The path for the new parent environment.; clone - The flag for whether to copy the environment(s).
Throws:: NullPointerException - Signals that resultHandler, envId, remoteHost, or remotePath is null.; IllegalArgumentException - Signals that the remote port is invalid.; SecurityException - Signals that the caller does not have permission to manage environments.
See Also:: MovingProtocol

getStatus

public int getStatus()

Get the current status for this environment.

Returns:: The current status for this environment.
Throws:: IllegalStateException - Signals that the system is not running.
See Also:: INACTIVE, ACTIVE, TERMINATING, DESTROYING, DESTROYED

activate

public static void activate(Guid requestorId,
                            Guid envId)

Activate the specified environment. Activating an already active environment has no effect.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to be activated.
Throws:: NullPointerException - Signals that envId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists.; NotLinkedException - Signals that the specified environment has not been linked against a main event handler.; IllegalStateException - Signals that the system is not running, that the specified environment is not in the active or inactive state, or that the specified environment is currently being modified.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified environment is not a descendant of the specified requesting environment.

terminate

public static void terminate(Guid requestorId,
                             Guid envId)

Terminate the specified environment. Terminating an already inactive or currently terminating environment has no effect.

Note that terminating an application does not unload the application. Its state remains loaded within the environment and it can be restarted through the activate operation. To unload an application, use the unload operation after terminating the application.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to be terminated.
Throws:: NullPointerException - Signals that envId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists or that the specified environment is the root environment.; IllegalStateException - Signals that the system is not running, or that the specified environment is currently being modified.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified environment is not a descendant of the specified requesting environment.

unload

public static void unload(Guid requestorId,
                          Guid envId)

Unload the code from the protection domain rooted at the specified environment. This method unlinks all exported event handlers from the main and monitor event handlers of the environments in the specified protection domain. It recreates the environments' concurrency domains, thus ensuring that other environments cannot call code in the specified protection domain anymore. It also recreates the environments' protection domain, thus ensuring that future loading operations load all code from scratch.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment rooting the protection domain to be unloaded.
Throws:: NullPointerException - Signals that envId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists.; IllegalStateException - Signals that the system is not running, or that an environment in the specified protection domain is not in the inactive state or is currently being modified.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified environment is not a descendant of the specified requesting environment.

destroy

public static boolean destroy(Guid requestorId,
                              Guid envId)
                       throws IOException

Destroy the specified environment and all its descendants. Destroying an environment that is already being destroyed or that has already been destroyed has no effect.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to be destroyed.
Returns:: true if the environment requesting the operation has been destroyed.
Throws:: NullPointerException - Signals that envId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists or that the specified environment is the root environment.; IOException - Signals an exceptional condition when deleting the persistent environment state for the destroyed environment(s).; IllegalStateException - Signals that the system has shut down.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified environment is not a descendant of the specified requesting environment.

checkPoint

public static long checkPoint(Guid requestorId,
                              Guid envId)
                       throws IOException

Check-point the specified environment and all its descendants. The root environment cannot be check-pointed.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to be check-pointed.
Returns:: The timestamp for the check-point.
Throws:: NullPointerException - Signals that envId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists, that the specified environment is the root environment, or that the specified environment's parent is in the same protection domain.; IOException - Signals an exceptional condition while actually creating the check-point.; IllegalStateException - Signals that the system has shut down, that the specified environment or one of its descendants is currently being modified, or that this method could not write to the specified environment's tuple store.; SecurityException - Signals that the caller does not have permission to manage environments, or that the specified environment is not a descendant of the specified requesting environment.

restore

public static boolean restore(Guid requestorId,
                              Guid envId,
                              long timestamp)
                       throws TupleException,
                              ClassNotFoundException

Restore the specified environment and all its descendants from the specified check-point. The root environment cannot be restored.

A saved check-point can only be restored if no environments have been added or destroyed in the local environment subtree underneath the specified environment. At the same time, if environments have been moved within the subtree, the check-point can be restored.

Note that restoring a check-point does not reload the application's code. To reload an application's code, the application needs to be terminated and unloaded before restoring the check-point.

Parameters:: requestorId - The ID of the environment requesting this operation.; envId - The ID of the environment to be restored.; timestamp - The timestamp of the check-point or -1 if the latest check-point is to be used.
Returns:: true if the environment requesting the operation has been restored.
Throws:: NullPointerException - Signals that envId is null.; IllegalArgumentException - Signals that no environment with the specified ID exists, that the specified environment is the root environment, that the specified timestamp is negative, or that no check-point with the specified timestamp exists.; TupleException - Signals that the requested check-point is corrupted or that the local environment subtree has changed since the check-point.; ClassNotFoundException - Signals that a class was not found while reading the requested check-point.; IllegalStateException - Signals that the system has shut down, that the specified environment or one of its descendants is currently being modified, that this method could not read from the specified environment's tuple store, or that the specified environment or one of its descendants is being destroyed while restoring the requested check-point.; SecurityException - Signals that the caller does not have permission to manage environments or that the specified environment is not a descendant of the specified requesting environment.

startUp

public static void startUp()
                    throws IOException

Start up the environment hierarchy. This method performs internal initialization, notably by reading the existing environment hierarchy from tuple storage.

Throws:: IOException - Signals an exceptional condition while accessing persistent environment state.; IllegalStateException - Signals that the environment hierarchy has already been started up or that is has been shut down.; SecurityException - Signals that the caller does not have permission to start up and shut down the system.

shutDown

public static void shutDown()

Shut down all environments. This method shuts down all environments without notifying anyone of the pending shutdown. It must not be called with a thread that belongs to any concurrency domain in the environment hierarchy.

Throws:: IllegalStateException - Signals that the environment hierarchy has already been started up or that is has been shut down.; SecurityException - Signals that the caller does not have permission to start up and shut down the system.

createNestedConcurrency

public static NestedConcurrencyDomain createNestedConcurrency(String service)

Create a new, nested concurrency domain.

Parameters:: service - The name of the service associated with the newly created nested concurrency domain.
Returns:: A new, nested concurrency domain.
Throws:: NullPointerException - Signals that service is null.; SecurityException - Signals that the caller does not have permission to manage environments.
See Also:: NestedConcurrencyDomain

wrapForNested

public static EventHandler wrapForNested(EventHandler handler,
                                         NestedConcurrencyDomain concurrency)

Wrap the specified event handler as a wrapped handler for the specified nested concurrency domain. If the specified event handler is not already wrapped, it is wrapped for the specified nested concurrency domain and returned.

Parameters:: handler - The event handler.; concurrency - The nested concurrency domain.
Returns:: The wrapped event handler.
Throws:: NullPointerException - Signals that handler or concurrency is null.; IllegalArgumentException - Signals that handler is already wrapped.; IllegalStateException - Signals that the system is not running.; SecurityException - Signals that the caller does not have permission to manage environments.
See Also:: createNestedConcurrency(String)

ensureName

public static void ensureName(String name)

Ensure that the specified name is a legal environment name. Legal environment names are between 1 and 64 characters long. They may only contain ASCII letters and numbers as well as the following other characters: '$', '(', ')', ',', '-', '_', and '.'. They must not be "." or "..". Environment names are case sensitive.

Parameters:: name - The name to check.
Throws:: NullPointerException - Signals that the specified name is null.; IllegalArgumentException - Signals that the specified name is not legal.

ensurePermission

public static void ensurePermission()

Ensure that the caller has the permission to manage environments.

Throws:: SecurityException - Signals that the caller does not have permission to manage environments.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Inner Class Summary
`static class`	`Environment.Descriptor` Implementation of an environment descriptor.

Field Summary
`static int`	`ACTIVE` The status code for an active environment.
`static int`	`DESTROYED` The status code for a destroyed environment.
`static int`	`DESTROYING` The status code for an environment that is being destroyed.
`static int`	`INACTIVE` The status code for an inactive environment.
`static int`	`TERMINATING` The status code for a terminating environment.

Method Summary
`static void`	`activate(Guid requestorId, Guid envId)` Activate the specified environment.
`static long`	`checkPoint(Guid requestorId, Guid envId)` Check-point the specified environment and all its descendants.
`static void`	`copy(Guid requestorId, Guid envId, Guid newParentId)` Copy the specified environment to the specified new parent.
`static Environment`	`create(Guid requestorId, Guid parentId, String name, boolean inherit)` Create a new child environment.
`static Environment`	`create(Guid requestorId, Guid parentId, String name, boolean inherit, String init, Object closure)` Create a new child environment.
`static NestedConcurrencyDomain`	`createNestedConcurrency(String service)` Create a new, nested concurrency domain.
`static boolean`	`destroy(Guid requestorId, Guid envId)` Destroy the specified environment and all its descendants.
`static void`	`ensureName(String name)` Ensure that the specified name is a legal environment name.
`static void`	`ensurePermission()` Ensure that the caller has the permission to manage environments.
`Environment`	`getChild(String name)` Get the child environment witht the specified name.
`List`	`getChildren()` Get the names of all child environments.
`ConcurrencyDomain`	`getConcurrencyDomain()` Get the concurrency domain for this environment.
`ComponentDescriptor`	`getDescriptor()` Get the component descriptor for this environment.
`Guid`	`getId()` Get the ID for this environment.
`Component.Importer`	`getMain()` Get the main imported event handler for this environment.
`Component.Importer`	`getMonitor()` Get the monitor imported event handler for this environment.
`String`	`getName()` Get the name for this environment.
`Environment`	`getParent()` Get the parent environment for this environment.
`Guid`	`getParentId()` Get the ID of the parent environment for this environment.
`String`	`getParentName()` Get the name of the parent environment for this environment.
`ProtectionDomain`	`getProtectionDomain()` Get the protection domain for this environment.
`EventHandler`	`getRequest()` Get the request exported event handler for this environment.
`static Environment`	`getRoot()` Get the root environment.
`int`	`getStatus()` Get the current status for this environment.
`Timer`	`getTimer1()` Get the timer for this environment.
`static void`	`load(Guid requestorId, Guid envId, String init, Object closure)` Load the specified initializer and execute it within the specified environment.
`static Environment`	`lookup(Guid id)` Look up the environment with the specified ID.
`Environment`	`lookupLocally(Guid id)` Locally look up the environment with the specified ID.
`static boolean`	`move(Guid requestorId, Guid envId, Guid newParentId)` Move the specified environment to the specified new parent.
`static void`	`moveAway(Guid requestorId, EventHandler resultHandler, Object resultClosure, Guid envId, String remoteHost, int remotePort, String remotePath, boolean clone)` Move the specified environment to the new parent environment with the specified path on the specified remote host.
`static void`	`rename(Guid requestorId, Guid envId, String name)` Rename the specified environment to the specified name.
`static Environment`	`resolve(Guid requestorId, Guid localRootId, String[] path)` Resolve the specified local root and path.
`static boolean`	`restore(Guid requestorId, Guid envId, long timestamp)` Restore the specified environment and all its descendants from the specified check-point.
`static void`	`shutDown()` Shut down all environments.
`static void`	`startUp()` Start up the environment hierarchy.
`static void`	`terminate(Guid requestorId, Guid envId)` Terminate the specified environment.
`String`	`toString()` Get a string representation for this environment.
`static void`	`unload(Guid requestorId, Guid envId)` Unload the code from the protection domain rooted at the specified environment.
`static EventHandler`	`wrapForNested(EventHandler handler, NestedConcurrencyDomain concurrency)` Wrap the specified event handler as a wrapped handler for the specified nested concurrency domain.

one.world.core Class Environment

INACTIVE

ACTIVE

TERMINATING

DESTROYING

DESTROYED

getDescriptor

getMain

getRequest

getMonitor

getTimer1

getId

getName

getConcurrencyDomain

getProtectionDomain

getParent

getParentId

getParentName

getChild

getChildren

toString

getRoot

create

create

load

lookup

lookupLocally

resolve

rename

move

copy

moveAway

getStatus

activate

terminate

unload

destroy

checkPoint

restore

startUp

shutDown

createNestedConcurrency

wrapForNested

ensureName

ensurePermission

one.world.core
Class Environment