java.lang.isolate
Class Isolate

java.lang.Object
  |
  +--java.lang.isolate.Isolate

public final class Isolate

extends Object

The Isolate class provides the means of creating and managing isolated computations and arranging for their communication with each other.

An isolated computation (or isolate) at a minimum shares no objects or mutable static state with any other computation. The Isolate object corresponding to an isolate supports operations on the isolated computation. Multiple isolates may hold an Isolate object corresponding to the same isolated computation (i.e. an Isolate instance is a "handle" to an isolate). In contrast an aggregate is defined as the set of isolates that share a common ancestor isolate.

By convention, capitalization is used to distinguish an Isolate class or class instance from a reference to the isolate abstraction.

For example, the following code will run the public static main method (which returns void and takes a single String[] argument) of the public class org.example.Main with the single argument "-help" in a new isolate. The output of the new isolate will be printed to the standard output streams of the invoking isolate:

 
   Isolate i = new Isolate("org.example.Main", new String[] { "-help" });
   i.start(null); 
 

In addition to a main class and its arguments, the constructor of an isolate can specify a Preferences-based "context" for the new isolate, redirect the standard I/O of the isolate, and establish communication with the isolate. Each of these topics are addressed in turn.

Context

The context parameter to the long Isolate constructor allows a creator to specify application-defined and system-defined parameters for the new isolate. For application-defined parameter, the new isolate can invoke Isolate.currentIsolateContext to retrieve the values. See the currentIsolateContext documentation for details on the standard and implementation-defined context parameters.

Class path

Part of the definition of an application is the application classpath, where the basic classes for the application are found. The Java runtime typically searches for classes in three sets of locations: the bootstrap class path, the installed extensions directory, and the application class path. The bootstrap class path and installed extensions directory are constant for the aggregate; only the application class path can be specified with a new isolate.

The application classpath is specified for a new isolate by the java.properties/java.class.path preference in the context (see currentIsolateContext). The current isolate's class path is readable from the java.class.path property. The bootstrap classpath is visible in the java.bootclass.path property.

Note that the definition of the elements of the java.class.path is specified by the implementation. (Usually, it consists of file system directories and the full path to .jar files, but it could be database schema names, URLs, etc.)

Class Caching

Some implementations may "cache" classes between execution of isolates, to share class name resolution costs and spread the costs of finding and loading bytecodes for example.

The only way such "class caching" could interfere with user expectations is when a new isolate is created that should contain the latest available version of a class and not a cached version. For example, when developing servlets, it would be helpful if the servlet engine (assuming it runs each servlet in its own isolate) used the latest development version of the servlet code being debugged and not the first version it encountered.

The Isolate API supports this sort of application through the preference java.class.allow-caching. This preference defaults to the value true; if set to false, the VM guarantees that the new isolate will find classes as if it had been started in a new aggregate (i.e., using whatever mechanism the classes are located with at the lowest levels of the VM).

The java.class.allow-caching property has no effect on the classes loaded by the bootstrap class loader or on the standard extension classes.

For some implementations, for example, one that looks for classes in a read-only repository (such as ROM memory), setting the java.class.allow-caching property to false will make no difference: there is no difference between any possibly "cached" classes and the repository versions.

Similarly, setting the java.class.allow-caching property to true does not guarantee that cached classes will be used. Implementations are free to implement full loading and resolution of classes in each isolate. Even implementations that do support caching will probably have restrictions on when class caching is used (for example, only for a specific, well-defined java.class.path).

Standard IO Redirection

The "standard" IO of an isolated computation (i.e., System.in, System.out and System.err) can be redirected by the creator of the isolate using the long constructor. The three IsolateMessage parameters represent the standard input, output and error streams, respectively.

The given IsolateMessage objects must contain valid IO object references (see IsolateMessage), or an exception will be thrown. The associated standard System stream will be initialized in the new isolate from the stream object. Additionally, copies (as if sent via a Link) of the messages will be available via currentIsolateIOBindings in the new isolate.

The following examples illustrate some of the scenarios supported. Parameters a and t in the example Isolate constructor calls are simply placeholders for the String[] mainArgs and TransientPreferences context parameters respectively.

Inheritance of streams from the creating isolate:

   // Similar to invoking 'java Foo'
   Isolate foo = new Isolate("Foo", a); 
   foo.start();
 

OR

   // Similar to invoking 'java Foo'
   Isolate me = Isolate.currentIsolate();
   IsolateMessage[] myStdio = Isolate.currentIsolateIOBindings();
   Isolate foo = new Isolate("Foo", a, t,
                             myStdio[0], myStdio[1], myStdio[2]);
   foo.start();
 

Redirection of input from a file:

   // Similar to invoking 'java Foo < infile'
   Isolate me = Isolate.currentIsolate();
   IsolateMessage[] myStdio = Isolate.currentIsolateIOBindings();
   FileInputStream in = new FileInputStream("infile");
   Isolate foo = new Isolate("Foo", a, t, 
  			   IsolateMessage.newFileInputStreamMessage(in),
  			   myStdio[1], myStdio[2]);
   foo.start();
 

Discarding output:

   // Similar to invoking 'java Foo > /dev/null'
   Isolate me = Isolate.currentIsolate();
   IsolateMessage[] myStdio = Isolate.currentIsolateIOBindings();
   Isolate foo = new Isolate("Foo", a, t, 
                             myStdio[0], null, myStdio[2]);
   foo.start();
 

Piping between sibling isolates:

   // Similar to invoking 'java Foo | java Bar'
   Isolate me = Isolate.currentIsolate();
   IsolateMessage[] myStdio = Isolate.currentIsolateIOBindings();
   Pipe pipe = Pipe.open();
   Isolate foo = new Isolate("Foo", a, t, 
                             myStdio[0],
                             IsolateMessage.newPipeSinkChannelMessage(pipe.sink()),
                             myStdio[2]);
   Isolate bar = new Isolate("Bar", a, t, 
                             IsolateMessage.newPipeSourceChannelMessage(pipe.source()),
                             myStdio[1], 
                             myStdio[2]);
   foo.start();
   bar.start();
 

Inter-Isolate communication

Because each isolate has its own logical heap and there are no visibly shared Java objects, isolates must communicate through other mechanisms. In addition to all of the pre-existing mechanisms, there are several isolate-specific mechanisms.

All pre-existing mechanisms that work between separate instances of the Java Virtual Machine should continue to work between isolates, such as network-based communication via sockets or RMI, the file system, persistent preferences, etc.

The following isolate-specific methods are also available:

Arguments for main()

The static main method in the initial class to start in a new isolate takes a String[] argument. The contents of the array are entirely application defined, and the array may be zero-length or null. Obviously, only objects convertible to String may be copied through this interface.

TransientPreferences

The TransientPreferences, or context, parameter to the long Isolate constructor provides a structured method for passing information to a new isolate. A logical copy of the TransientPreferences object passed by the parent is available to the child via the static currentIsolateContext method. See the method documentation for details of the format of the standardized areas of the context parameter.

System properties

System properties are the properties readable through System.getProperty. In addition to the standard properties outlined in the documentation for getProperties() (and elsewhere in the java specification), properties can contain VM-defined properties and application-defined properties. By default, a new isolate receives a copy of the aggregate default property values. The java.properties/ node of a new isolate's context allows a creator to specify properties for the new isolate.

Standard streams (System.in, System.out, and System.err)

The standard i/o parameters of the long constructor can be used to establish byte-oriented connections between an isolate and its creator. See Standard IO Redirection.

Initial Messages

Initial messages can be passed via the start method and retrieved in the new isolate via the static currentIsolateStartMessages method. The initial messages can be used for passing one-time messages, or for establishing new communication channels See IsolateMessage for details.

The initial class

The initial class provided to a new isolate can also be used as means of supplying information to the new isolate by coding information into the class. For example, a class that initializes the security environment of a new isolate to a well-defined state might be useful. Such classes are usually only useful if they subsequently load and initialize another class.

Since:

JDK1.5

See Also:

Link, IsolateEvent, IsolatePermission, IsolateResourceError, IsolateStartupException, Link.newEventLink(java.lang.isolate.Isolate, java.lang.isolate.Isolate)

Constructor Summary

Isolate(String mainClass, String[] mainArgs)
Creates a new isolated java application with a default configuration.

Isolate(String mainClass, String[] mainArgs, TransientPreferences context, java.lang.isolate.IsolateMessage stdin, java.lang.isolate.IsolateMessage stdout, java.lang.isolate.IsolateMessage stderr)
Creates a new isolated java application with the specified context and standard i/o bindings.

Method Summary

static java.lang.isolate.Isolate	currentIsolate() Returns an Isolate object corresponding to the currently executing isolate.
static TransientPreferences	currentIsolateContext() Returns the context associated with the current isolate.
static java.lang.isolate.IsolateMessage[]	currentIsolateIOBindings() Retrieves a copy of the IsolateMessage array defining the initial "standard" i/o bindings of the current isolate.
static java.lang.isolate.IsolateMessage[]	currentIsolateStartMessages() Retrieves a copy of the IsolateMessage array passed to start by the current isolate's creator.
boolean	equals(Object obj) Tests this Isolate for equality with the given object.
void	exit(int status) Requests normal termination of the isolate this Isolate represents.
void	halt(int status) Forces termination of the isolate this Isolate represents.
boolean	hasExited() Returns true if the isolate this Isolate represents has reached the exiting state.
int	hashCode() Returns the hashcode for this Isolate.
boolean	hasStarted() Returns true if the isolate this Isolate represents has reached the starting state.
boolean	hasTerminated() Returns true if the isolate this Isolate represents has reached the terminated state.
java.lang.isolate.Link	newEventLink() Gets a new Link associated with this Isolate from which the current isolate can receive events.
void	start(java.lang.isolate.IsolateMessage[] messages) Indicate that the isolate this Isolate represents is to begin execution.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Isolate

public Isolate(String mainClass,
               String[] mainArgs)
        throws IsolateStartupException

Creates a new isolated java application with a default configuration.

This constructor has the same effect as invoking the long constructor and passing null for the context and the first three IsolateMessages returned from currentIsolateIOBindings (padding with null if less than three are returned).

If mainArgs is null, a zero-length String[] will be provided to the main method of mainClass.

See the long constructor documentation for more details.

Parameters:

mainClass - fully qualified name of the main method class

mainArgs - the arguments of the main method in the new isolate or null

Throws:

SecurityException - if a SecurityManager is present and it denies IsolatePermission("create").

IsolateResourceError - if insufficient resources are available to create the isolate

IsolateStartupException - if an error occurs in the configuration or startup of the new isolate before any application code is invoked

NullPointerException - if mainClass is null

Isolate

public Isolate(String mainClass,
               String[] mainArgs,
               TransientPreferences context,
               java.lang.isolate.IsolateMessage stdin,
               java.lang.isolate.IsolateMessage stdout,
               java.lang.isolate.IsolateMessage stderr)
        throws IsolateStartupException

Creates a new isolated java application with the specified context and standard i/o bindings. When started the new isolate will execute the public main method of public class mainClass with arguments mainArgs. The mainClass parameter must reference a class present in one of the classpath elements of the java.class.path property of the new isolate, or be present in the aggregate-wide bootstrap or extension class paths.

When the constructor returns, the new isolate is not running (as far as the user can tell). The new isolate does not really start until the start method is invoked. No events are delivered to any registered listeners until after start is invoked. The halt and exit methods will fail if invoked between construction time and start time.

Because class resolution and loading are performed by the new isolate, any loading exceptions (such as ClassNotFoundException) will occur in the new isolate (not the creator) when it is started.

Changes made to any of the constructor's parameters after control returns from this constructor will have no effect on the newly created isolate.

If mainArgs is null, a zero-length String[] will be provided to the main method of mainClass.

If the context parameter is null, a default, system-defined context will be supplied to the new isolate. The context parameter can contain app-specific and/or system-specific arguments, including system properties for the new isolate. See Isolate.currentIsolateContext for details on the system defined entries and their semantics. By default, a new isolate gets a copy of the aggregate default system properties. The system may modify the context as it is copied into the child.

If the stdin, stdout, or stderr bindings are null then a null device binding is passed to the created isolate. A null device returns EOF on reads and ignores writes. If not null these binding parameters must be IsolateMessage objects wrapping valid i/o types (see IsolateMessage). A creating isolate may pass on its own bindings by, for example, using the appropriate IsolateMessage returned from currentIsolateIOBindings.

Jar Files

To execute a jar file in a new isolate (similar to the -jar option supported by some java commands), the "Main-Class" attribute must be extracted from the jar's manifest. Additionally, the jar file must be placed on the class path for the new isolate.

The following example loads and executes "app.jar" in a new isolate. First, the name of the main class is extracted from the jar's manifest:

 String jarFileName = "app.jar";
 String mainClassName = new java.util.jar.JarFile(jarFileName)
     .getManifest()
     .getMainAttributes()
     .getValue(java.util.jar.Attributes.Name.MAIN_CLASS);
 

Second, the java.class.path property for the new isolate is set with the name of the jar file.

 TransientPreferences p = new TransientPreferences();
 p.put("java.properties/java.class.path", jarFileName);
 

Finally, the isolate is created and started with the main class and the preferences containing the appropriate classpath.

 Isolate jarIsolate = new Isolate(mainClassName, null, p, null);
 jarIsolate.start(null);
 

Implementation Notes

An implementation of the Isolate class has latitude as to when the underlying isolate container is actually created and initialized. The implementation is free to just hold on to the constructor parameters or to start a new container for the isolated application and begin execution of system code in that new container. The only restriction is that no "user code" (no main method, no static initializers, etc.) is executed in the new isolate before start is invoked.

Note that implementations that start the underlying isolate container at construction time may have to garbage collect it if start is never invoked and the Isolate becomes unreferenced.

Implementations that start asynchronous execution of the isolate's system code at construction time must deal with buffering errors in the child until start time.

"User code" can be defined as code loaded off the java.class.path. Bootstrap classes, standard classes, and extension classes can be considered "system code."

Parameters:

mainClass - fully qualified name of the main method class

mainArgs - the arguments for the main method in the new isolate

context - the application context and system properties or null

stdin - an IsolateMessage containing a valid I/O object or null

stdout - an IsolateMessage containing a valid I/O object or null

stderr - an IsolateMessage containing a valid I/O object or null

Throws:

SecurityException - if a SecurityManager is present and it denies IsolatePermission("create").

IsolateResourceError - if insufficient resources are available to create the isolate

IsolateStartupException - if an error occurs in the configuration or startup of the new isolate before any application code is invoked

IllegalArgumentException - if any parameters are found to be invalid

NullPointerException - if mainClass is null

See Also:

currentIsolateContext()

Method Detail

start

public void start(java.lang.isolate.IsolateMessage[] messages)
           throws IsolateStartupException

Indicate that the isolate this Isolate represents is to begin execution. Prior to this method's use, no application code (including static initializers) has been executed. Control will return from this method when the new isolate's first user level thread starts executing or if an error occurs during the initialization of the new isolate.

After start has been invoked (and potentially before it returns), the "started" event will be delivered on any relevant event links.

The given array of IsolateMessage objects will be copied as if sent on a Link, and will be available in the new isolate via currentIsolateStartMessages().

A null messages parameter results in the new isolate getting a zero length array of IsolateMessage objects. Changes to the messages parameter following return from this method will have no effect on the started isolate.

Any null entries in the IsolateMessage array will cause an IllegalArgumentException to be thrown.

If any given IsolateMessage contains a serializable object, then start may throw an IsolateStartupException which will chain a LinkSerializationException if any serialization errors occur.

A SecurityException will be thrown if the invoker does not have permission to send the given type of IsolateMessage.

An IllegalArgumentException will be thrown if any given IsolateMessage contains an Isolate that has not been started.

If any exception is thrown by this method, no application code will have executed. Additionally, exactly one of the two following cases will hold:

• The starting, stopping, and terminated events were sent on any associated event link. This Isolate is terminated.
• No events were delivered, so the isolate is not terminated, nor is it considered "started." A subsequent invocation of start may succeed.

Errors such as the main class being invalid or not visible in the java.class.path will generally be handled within the new isolate by the default uncaught exception handler.

Parameters:

messages - an array of zero or more IsolateMessages objects or null

Throws:

IllegalStateException - if this isolate was already started or is terminated or if start was invoked in a different isolate from the creator

IsolateResourceError - if insufficient resources to create and/or start this isolate

IsolateStartupException - if an error occurs in the initialization or configuration of the new isolate before any application code is invoked.

SecurityException - if the messages parameter is non-null and a SecurityManager is present and it denies permission to send any given type of IsolateMessage in messages.

IllegalArgumentException - if the messages parameter is non-null but contains a null reference or contains a reference to an unstarted isolate.

See Also:

Link, IsolateEvent.Type.STARTING, currentIsolateStartMessages()

currentIsolateIOBindings

public static java.lang.isolate.IsolateMessage[] currentIsolateIOBindings()

Retrieves a copy of the IsolateMessage array defining the initial "standard" i/o bindings of the current isolate. In the typical case the creator isolate defines bindings for standard input, output and error respectively and this method will return a array whose elements correspond to the three standard streams. The atypical case is for an isolate started by the implementation (i.e., the first isolate in an aggregate). In this case, the array contains one element for each of the initial i/o bindings defined by the environment that started the aggregate.

Modification of this array will have no effect on subsequent invocation of this method.

This method never returns null: it will return a zero-length array if no bindings are defined.

Returns:

an array of zero or more IsolateMessage objects

Throws:

SecurityException - if a SecurityManager is present and it denies IsolatePermission("context")

See Also:

Isolate(String,String[],java.util.prefs.TransientPreferences, IsolateMessage, IsolateMessage, IsolateMessage)

currentIsolateStartMessages

public static java.lang.isolate.IsolateMessage[] currentIsolateStartMessages()

Retrieves a copy of the IsolateMessage array passed to start by the current isolate's creator. Modification of this array will have no effect on subsequent invocation of this method.

This method never returns null: it will return a zero-length array if null was passed to start by the parent isolate.

Returns:

an array of zero or more IsolateMessage objects

Throws:

SecurityException - if a SecurityManager is present and it denies IsolatePermission("context")

exit

public void exit(int status)

Requests normal termination of the isolate this Isolate represents. Invocation of this method is equivalent to causing the isolate to invoke Runtime.exit(int). If this method invocation is, in fact, the cause of the isolate's termination, the status supplied will be the isolate's termination status.

Note that this method is not synchronous with the state change of the isolate in question. Monitoring of events can be used to confirm termination or the isolate state can be polled with hasTerminated().

No exception is thrown if this isolate is already terminated. Even if hasTerminated() returns false prior to invoking exit, an invocation of exit may occur after the isolate exits on its own or is terminated by another isolate. In these cases, the actual exit code reported by the isolate may be different from the one specified.

If a security manager is present the user of this method must have the "control" IsolatePermission and appropriate additional permissions.

Parameters:

status - By convention, a nonzero status code indicates abnormal termination

Throws:

IllegalStateException - if this isolate is not yet started

SecurityException - if a SecurityManager is present and it denies IsolatePermission("control")

See Also:

IsolateEvent.Type.TERMINATED, IsolateEvent.getExitStatus()

halt

public void halt(int status)

Forces termination of the isolate this Isolate represents. Invocation of this method is equivalent to causing the isolate to invoke Runtime.halt(int). If this method invocation is in fact the cause of the isolate's termination, the status supplied will be the isolate's termination status.

Note that this method is not synchronous with the state change of the isolate in question. Monitoring of events can be used to confirm termination or the isolate state can be polled with hasTerminated().

No exception is thrown if this isolate is already terminated. Even if hasTerminated() returns false prior to invoking halt, an invocation of halt may occur after the isolate exits on its own or is terminated by another isolate. In these cases, the actual exit code reported by the isolate may be different from the one specified.

If a security manager is present the user of this method must have the "control" IsolatePermission and appropriate additional permissions.

Implementation Note

Implementations should strive to implement "quick" termination with as little coordination with the target isolate as possible. The only information required of a terminated isolate is the exit code it was terminated with.

Parameters:

status - Termination status. By convention, a nonzero status code indicates abnormal termination.

Throws:

SecurityException - if a SecurityManager is present and it denies IsolatePermission("control")

IllegalStateException - if this isolate is not yet started

hasStarted

public boolean hasStarted()

Returns true if the isolate this Isolate represents has reached the starting state. Once STARTING is reached this method will never again return false.

Returns:

true if the STARTING state has been reached

See Also:

IsolateEvent.Type.STARTING

hasExited

public boolean hasExited()

Returns true if the isolate this Isolate represents has reached the exiting state. Once EXITING is reached this method will never again return false.

Returns:

true if the EXITING state has been reached

See Also:

IsolateEvent.Type.EXITING

hasTerminated

public boolean hasTerminated()

Returns true if the isolate this Isolate represents has reached the terminated state. Once TERMINATED is reached this method will never again return false.

Returns:

true if the TERMINATED state has been reached

See Also:

IsolateEvent.Type.TERMINATED

newEventLink

public java.lang.isolate.Link newEventLink()
                                    throws ClosedLinkException

Gets a new Link associated with this Isolate from which the current isolate can receive events.

This method is equivalent to:

   Link.newEventLink(this, Isolate.currentIsolate());
 

See the Link.newEventLink method for further details.

Returns:

a new Link associated with this isolate

Throws:

IsolateResourceError - if there are insufficient resources to allocate the link

ClosedLinkException - if this isolate is in the terminated state

currentIsolate

public static java.lang.isolate.Isolate currentIsolate()

Returns an Isolate object corresponding to the currently executing isolate.

This method never returns null.

Returns:

the Isolate object for the current isolate

currentIsolateContext

public static TransientPreferences currentIsolateContext()

Returns the context associated with the current isolate. The returned context is a deep copy of the context parameter supplied by the creator when the current isolate was created, or a default context if none was supplied by the creator. The returned context may have been modified by the system when it was copied.

This method never returns null. The first isolate in a new aggregate is provided with a non-null context which will contain standard default values, and may contain implementation-specific default values.

Changes to the context are not reflected in any other isolate. However, the returned preferences object is mutable.

The usage of a TransientPreferences instance for defining a new isolate's "context" can be broken down into several categories. The context can be used to set standard preferences, implementation-specific preferences, and application specified preferences. The context also allows a creator to specify system properties (i.e., those available from System.getProperty). The default context and how an application-provided context will be merged are defined here.

Standard Context Preferences

The name space of the context preferences object is structured similarly to the Java class name space. The java. and javax. prefixes are reserved for standard, system-defined names defined by a Java API; for non-standard names a reverse-domain-name prefix convention is encouraged (e.g. "org.apache.neatfeature").

Some preferences are meant to be used by a parent (to specify a configuration option for a new isolate). Some are meant to be used by the current isolate (to query its environment or settings from its parent).

The following context preferences are defined in the java.* name space by this specification:

Name	Type	Definition	Usage
java.class.allow-caching	Boolean	A hint for class caching. See Class Caching.	Settable by a parent. Not required to be set in child.
java.lang.isolate.jni-isolatation	Boolean	True if isolation of JNI code is supported in this isolate, false otherwise. JNI isolation implies that faults or errors in user-loaded JNI code will be isolated from other isolate's JNI code.	Not settable by a parent (will be ignored). Required to be defined in child.
java.lang.isolate.vm-isolatation	Boolean	True if isolation of JVM internal code is supported in this isolate, false otherwise. VM isolation implies that a fault or error in the VM may only terminate this isolate (and not the entire aggregate). Of course, faults in the code that implements isolation probably cannot be isolated.	Not settable by a parent (will be ignored). Required to be defined in child.
java.properties/	node	Contains properties to set in a child isolate. See System Properties below.	Settable by a parent. Will not be visible in child, access to properties must be done through the standard System properties interfaces.

Implementation Specific Preferences

This specifications only covers those parts of the transient preferences namespace with a standard prefix. A reverse-domain-name prefix convention is suggested for vendor specific preferences (e.g. "edu.utah.cs.janosopts"). The only exception to this convention is the "options" key shown below, intended for passing a collection of implementation-defined options:

Name	Type	Definition
options	String	Java implementation-specific options e.g. "-Xmx64m -Xcheck:jni"

Application Preferences

Any portion of the transient preferences namespace not defined by standard or implementation-specific preferences is available for defining application state using the full set of types and naming hierarchy. Use of Preferences in place of System Properties for communicating application state is strongly recommended (unless per-name access checks are required as only Properties provides fine-grained access control).

Properties

Any entries in the "java.properties/" node, (if the node exists), will have the node prefix stripped and be set as a String in the System Properties of the new isolate. The property values can then be accessed within the new isolate via the normal manner (e.g., System.getProperty). For example, putting the key "java.properties/org.tullmann.prop" with value "prop value" in the context for a new isolate will cause the system property "org.tullmann.prop" to be set to "prop value" in the new isolate. While properties are defined by a parent in the "java.properties/" node of the context, properties are not accessible in the new isolate via the context (they must be accessed via existing means).

System Properties

Properties defined by other parts of the Java standard, for example, Java Security properties and JNDI properties, will be honored on a per-isolate basis. For example, adding "java.properties/java.security.manager" to a new isolate's context will enable the default security manager in that isolate as specified by the Java 2 Platform Security Architecture.

However, many of the standardized system properties documented on System.getProperties may be silently ignored if set in "java.properites/". For many of them, the code that reads and uses them may execute once at aggregate startup time (and thus per-isolate values will not be used for anything). Only the "java.class.path" property is guaranteed to be honored on a per-isolate basis. The behavior of setting any other such property is implementation-specific. For example, setting the property "file.separator" in a new isolate may or may not set that property in the new isolate, and even if the property is set in the new isolate, it may or may not have an impact. The only portable usage of these properties in a context is to not set them on a per-isolate basis (excepting "java.class.path").

The following table lists the properties from System.getProperties whose per-isolate behavior are implementation-defined:

Key	Description of Associated Value
java.version	Java Runtime Environment version
java.vendor	Java Runtime Environment vendor
java.vendor.url	Java vendor URL
java.home	Java installation directory
java.vm.specification.version	Java Virtual Machine specification version
java.vm.specification.vendor	Java Virtual Machine specification vendor
java.vm.specification.name	Java Virtual Machine specification name
java.vm.version	Java Virtual Machine implementation version
java.vm.vendor	Java Virtual Machine implementation vendor
java.vm.name	Java Virtual Machine implementation name
java.specification.version	Java Runtime Environment specification version
java.specification.vendor	Java Runtime Environment specification vendor
java.specification.name	Java Runtime Environment specification name
java.class.version	Java class format version number
java.library.path	List of paths to search when loading libraries
java.io.tmpdir	Default temp file path
java.compiler	Name of JIT compiler to use
java.ext.dirs	Path of extension directory or directories
os.name	Operating system name
os.arch	Operating system architecture
os.version	Operating system version
file.separator	File separator ("/" on UNIX)
path.separator	Path separator (":" on UNIX)
line.separator	Line separator ("\n" on UNIX)
user.name	User's account name
user.home	User's home directory
user.dir	User's current working directory

Implementation Specific Properties

Implementation-specific properties (e.g., those prefixed with "com.sun.", etc.) are implementation-defined with respect to their per-isolate or aggregate-wide nature.

Default Context

If a creator passes null for the context parameter to the long Isolate constructor, the system will create a preferences object in the new isolate. This preferences object will have standard preferences as defined above, and may contain implementation-defined preferences.

Default system properties

The set of system properties defined in a new isolate is a combination of the aggregate default system properties, implementation-defined properties, and the properties provided by the parent in the context argument. Properties provided by the context take precedence over aggregate default system properties, except for the exceptional cases listed above. The precedence relation of parent-provided properties and implementation-defined properties is implementation-defined.

For example, consider the standard system properties "java.vendor" and "java.class.path". The property "java.vendor" is an exceptional case, so its value in a new isolate will most likely be the aggregate default value, regardless of what the parent provides (though the exact behavior is implementation-defined). The "java.class.path" property will default to the aggregate default value, but any parent-provided value will take precedence.

Relation between parent and child context

The values defined in the "java.properties" node of a context are not made available in the child's copy of the context. The child isolate must access the values for any properties through existing property access mechanisms (i.e., System.getProperty).

All other preferences in the context returned by Isolate.currentIsolateContext() in a child isolate reflect the values provided by the parent. Implementations are free to define additional entries in the returned context. For example, an implementation could report the value of a special feature containing an isolate in a context entry (e.g., "org.javafun.mpisolate.turbomode"). Any value provided by a parent for these kinds of implementation-defined properties will be ignored.

Returns:

context for the current isolate

Throws:

SecurityException - if a SecurityManager is present and it denies IsolatePermission("context")

hashCode

public int hashCode()

Returns the hashcode for this Isolate.

Overrides:

hashCode in class Object

Returns:

the hashcode

equals

public boolean equals(Object obj)

Tests this Isolate for equality with the given object. Returns true if and only if obj is not null and denotes the same isolated computation as this.

Overrides:

equals in class Object

Parameters:

obj - The object to be compared

Returns:

true if the objects are the same; false otherwise