com.sun.cldc.isolate
Class Isolate

java.lang.Object
  com.sun.cldc.isolate.Isolate

public final class Isolate
extends Object

Last modified: 05/03/31 13:22:49.

Note: this document is still a draft. Details in the API are subject to change.

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

Terminology

Each isolated computation is called a Task. An Isolate object is a Java representation of the task. Multiple Isolate objects may be created to represent the same task. Where the context is clear, the words "task", "isolate" and "isolate object" may be used interchangeably. When a distinction needs to be made, the word "task" is used to describe the underlying computation, and the word "isolate" is used to describe the Java object(s) that represent the computation.

When two Isolate objects represent the same task, they are said to be equivalent to each other. Equivalent Isolate objects are created to avoid the sharing of Isolate objects across task boundaries. For example, in the following program, task A launches task B using the object b1, and task B gets a reference to itself using the object b2. b1 and b2 are two distinct objects:

class TaskA {
    void launchB() {
        Isolate b1 = new Isolate("TaskB", ....);
        b1.start();
    }
}
class TaskB {
    public static void main(String args[]) {
        Isolate b2 = Isolate.currentIsolate();
    }
}

Degree of Isolation

Tasks in the CLDC environment are isolated in the following sense:

• Each task has a separate namespace for loading Java classes.
• Each task has a separate set of static variables for Java classes
• A synchronized static method uses a different monitor object inside each task.
• Typically no Java objects are shared across task boundaries. (see Object Sharing below for exceptions).
• Resource quotas are controlled by the runtime environment to prevent tasks to use excessive amount of resources. The implementation currently supports resource control for memory or CPU cycles.

Class path

Part of the definition of an isolate is its classpath, where the basic classes for the isolate are found. The CLDC runtime searches for classes in three sets of locations:

• The romized system classes.
• The isolate system class path.
• The isolate application class path.

System and application class paths are specified separately for an isolate when it is created. Classes on system and application class paths have different access rights:

• Only classes loaded from the system class path can access hidden classes.
• Only classes on the system class path can be loaded to restricted packages.

For the definition of hidden and restricted packages, see doc/misc/Romizer.html.

When an isolate requests a class, the class is first looked up the romized system classes, then searched in the isolate system class path, and then searched in the isolate application class path.

User application classes should be put on the application class path, system class path can contain only trusted system classes.

WARNING: UNTRUSTED USER APPLICATION CLASSES MUST NEVER BE PUT ON THE SYSTEM CLASS PATH, AS IT GRANTS THEM ACCESS TO SYSTEM INTERNALS AND BREAKS SYSTEM SECURITY.

Object Sharing

The Isolate API in CLDC does not support the sharing of arbitrary Java object across Isolate boundaries. The only exception is String objects: String objects may be passed as arguments from a parent isolate to a child isolate's main() method. Such Strings are passed by reference instead of by value in order to conserve resource. Also, interned Strings (such as literal Strings that appear inside Java source code) may be shared across Isolate boundaries.

Even though String objects may be shared across isolates, different isolates should not attempt to coordinate their activities by synchronizing on these Strings. Specifically, an interned Strings cannot be synchronized across isolate boundaries because it uses a different monitor object in each Isolate.

Inter-Isolate Communication

Isolates may need to communicate with each to coordinate their activities. The recommended method of inter-isolate communication is a native event queue. On many CLDC/MIDP environments a native event queue already exists. Such event queues can be extended for one isolate to send events to another isolate.

Some CLDC/MIDP implementors may be tempted to use native code to pass shared objects from one isolate to another, and use traditional Java object-level synchronization to perform inter-isolate communication. In our experience this could easily lead to inter-isolate deadlock that could be exploited by downloaded malicious Midlets. For example, if a shared object is used to synchronize screen painting, a malicious Midlet may stop other Midlets from painting by not returning from its paint() method.

In our experience, with shared objects, it would take significant effort to design a system that can prevent such attacks. In contrast, event queues are much more easily understood to design a safe environment. Thus, we strongly recommend against using shared objects for inter-isolate communication.

The following code is an example of how an isolate can create other isolates:

import com.sun.cldc.isolate.*;

class HelloWorld {
 
    // Usage: cldc_vm -classpath  HelloWorld HelloWorld2 
    public static void main(String [] argv) {
        System.out.println("HelloWorld");
        for (int i = 0; i < 6; i++) {
            try {
                // pass i as an argument to the isolate just for fun 
               String[] isoArgs = {Integer.toString(i)};
                Isolate iso = new Isolate(argv[0], isoArgs);
                iso.start();
             } catch (Exception e) {
                System.out.println("caught exception " + e);
                e.printStackTrace();
            }
            System.out.println("HelloWorld: Iso " + i + " started.");

        }
    }
}


class HelloWorld2 {
    static String st = "HelloWorld2[";

    public static void main(String [] argv) {
        st = st.concat(argv[0]);
        st = st.concat("]");
        System.out.println("st is " + st);
        System.exit(42);
    }
} 

See Also:

javax.isolate.IsolateStartupException

Field Summary

static int	MAX_PRIORITY The maximum priority that an Isolate can have.
static int	MIN_PRIORITY The minimum priority that an Isolate can have.
static int	NORM_PRIORITY The default priority that is assigned to an Isolate.

Constructor Summary

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

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

Isolate(String mainClass, String[] mainArgs, String[] app_classpath, String[] sys_classpath)
Creates a new Isolate with the specified arguments and classpath.

Method Summary

void	attachDebugger()
static Isolate	currentIsolate() Returns the Isolate object corresponding to the currently executing task.
void	exit(int status) Requests normal termination of this Isolate.
int	exitCode() Returns the exit code of the isolate.
String[]	getClassPath() Returns the classpath the Isolate was started with.
static Isolate[]	getIsolates() Returns an array of Isolate objects representing all tasks that have been started but have not terminated.
int	getPriority() Returns the priority of this isolate.
void	halt(int status) Forces termination of this Isolate.
int	id() Returns a small integer ID that uniquely identifies this Isolate among the current set of active Isolates.
boolean	isDebuggerConnected() Indicates if debugger connection is established with the VM.
boolean	isSuspended() Returns if this isolate has been suspended.
boolean	isTerminated() Returns true if this Isolate is terminated.
int	reservedMemory()
void	resume() The opposite of the suspend method.
void	setAPIAccess(boolean access) Sets the access to Isolate API for this Isolate.
void	setDebug(boolean mode)
void	setHiddenPackages(String[] package_names) Sets the packages which will be hidden.
void	setMemoryQuota(int reserved) Sets the object heap memory reserved and maximum limits to the same value.
void	setMemoryQuota(int reserved, int total) Sets the object heap memory quota for this Isolate.
void	setPriority(int new_priority) Adjust the priority of this Isolate.
void	setProfile(String profile) Sets active profile name for isolate.
void	setRestrictedPackages(String[] package_names) Sets the packages which will be restricted.
void	setUseProfiler(boolean useProfiler) Sets whether isolate should be profiled or not.
void	setUseVerifier(boolean verify) Controls whether or not classes for this isolate need to be verified.
void	start() Start execution of this Isolate.
void	suspend() Suspends all threads in this isolate from execution.
int	totalMemory()
long	uniqueId() Returns a 64-bit ID that uniquely identifies this Isolate.
int	usedMemory() This function returns the approximate amount of object heap memory currently used by this Isolate.
void	waitForExit() Blocks the execution of the calling thread until this Isolate has exited.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MIN_PRIORITY

public static final int MIN_PRIORITY

The minimum priority that an Isolate can have.

See Also:

Constant Field Values

NORM_PRIORITY

public static final int NORM_PRIORITY

The default priority that is assigned to an Isolate.

See Also:

Constant Field Values

MAX_PRIORITY

public static final int MAX_PRIORITY

The maximum priority that an Isolate can have.

See Also:

Constant Field Values

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 Isolate(String,String[],String[]) and passing null for the app_classpath and sys_classpath parameters. 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

Throws:

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

Isolate

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

Creates a new isolated java application with a default configuration.

This constructor has the same effect as invoking Isolate(String,String[],String[], String[]) and passing null for the sys_classpath parameter. 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

app_classpath - the application classpath(s) for the isolate (see Class path)

Throws:

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

Isolate

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

Creates a new Isolate with the specified arguments and classpath.

The new isolate will execute the main method of class mainClass with arguments mainArgs. The mainClass parameter must reference a class present in the romized system classes, or in one of the classpath elements specified by the sys_classpath and app_classpath parameters.

When the constructor returns, the new isolate is not yet running. The new isolate does not start execution until the start method is invoked. The halt and exit methods will fail if before start is invoked.

Class resolution and loading are performed in the new task represented by this new isolate. Any loading exceptions (such as ClassNotFoundException), including the loading exception of the specified mainClass, will occur inside the new task when it is started, not the creator task.

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 array will be provided to the main method of mainClass.

User application classes should be put on app_classpath, while sys_classpath can contain only trusted system classes.

WARNING: UNTRUSTED USER APPLICATION CLASSES MUST NEVER BE PUT ON THE SYSTEM CLASS PATH, AS IT GRANTS THEM ACCESS TO SYSTEM INTERNALS AND BREAKS SYSTEM SECURITY.

Parameters:

mainClass - fully qualified name of the main method class

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

app_classpath - the application classpath(s) for the isolate

sys_classpath - the system classpath(s) for the isolate (see Class path)

Throws:

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

IllegalArgumentException - if any parameters are found to be invalid.

Method Detail

start

public void start()
           throws IsolateStartupException

Start execution of this Isolate. Any code that belongs to this Isolate (including static initializers) is executed only after this method is called.

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.

If any exception is thrown by this method, no code in the Isolate will have executed.

Errors such as the main class being invalid or not visible in the classpath will occur handled within the new isolate.

Throws:

IsolateStartupException - if an error occurs in the initialization or configuration of the new isolate before any application code is invoked, or if this Isolate was already started or is terminated.

IsolateResourceError - if systems exceeds maximum Isolate count

OutOfMemoryError - if the reserved memory cannot be allocated

exit

public void exit(int status)

Requests normal termination of this Isolate. 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.

No exception is thrown if this isolate is already terminated. Even if isTerminated() 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 status.

If this isolate is not yet started, it will be marked as already terminated. A subsequent invocation to start() would result in an IsolateStartupException.

If this isolate is suspended, it will be terminated without being resumed.

Parameters:

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

halt

public void halt(int status)

Forces termination of this Isolate. If this method invocation is in fact the cause of the isolate's termination, the status supplied will be the isolate's termination status.

No exception is thrown if this isolate is already terminated. Even if isTerminated() 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 status.

If this isolate is not yet started, it will be marked as already terminated. A subsequent invocation to start() would result in an IsolateStartupException.

If this isolate is suspended, it will be terminated without being resumed.

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.

isTerminated

public boolean isTerminated()

Returns true if this Isolate is terminated.

currentIsolate

public static Isolate currentIsolate()

Returns the Isolate object corresponding to the currently executing task.

This method never returns null.

Returns:

the Isolate object for the current task

getIsolates

public static Isolate[] getIsolates()

Returns an array of Isolate objects representing all tasks that have been started but have not terminated. New tasks may have been constructed or existing ones terminated by the time this method returns.

Returns:

the active Isolate objects at the time of the call

id

public int id()

Returns a small integer ID that uniquely identifies this Isolate among the current set of active Isolates. The returned ID will remain unchanged and reserved for this Isolate during its entire lifetime. However, after this Isolate is terminated, the ID may be resumed for a new Isolate.

Returns:

-1 if the task has not been started or it has been terminated,

uniqueId

public long uniqueId()

Returns a 64-bit ID that uniquely identifies this Isolate. The ID is assigned when the Isolate is created and will remain unchanged and reserved for this Isolate during the entire lifetime of the VM.

reservedMemory

public int reservedMemory()

Returns:

the amount of object heap memory reserved for this Isolate.

totalMemory

public int totalMemory()

Returns:

the maximum amount of object heap memory that can be allocated by this Isolate.

usedMemory

public int usedMemory()

This function returns the approximate amount of object heap memory currently used by this Isolate. The approximate value may not be accurate: it may not include recent allocations made by the Isolate, and it may count objects allocated by the Isolate that have since become unreachable.

Returns:

the approximate amount of object heap memory currently used by this Isolate.

setMemoryQuota

public void setMemoryQuota(int reserved)

Sets the object heap memory reserved and maximum limits to the same value. Note that if the system does not have sufficient resources to guaranteed the reserved amount, the start() method of this Isolate would fail. This method should only be called before the Isolate is started. Calling it after the isolate has started will cause undetermined behavior.

Parameters:

reserved - The minimum amount of memory guaranteed to be available to the isolate at any time. Also the total amount of memory that the isolate can reserve.

setMemoryQuota

public void setMemoryQuota(int reserved,
                           int total)

Sets the object heap memory quota for this Isolate. Note that if the system does not have sufficient resources to guaranteed the reserved amount, the start() method of this Isolate would fail. This method should only be called before the Isolate is started. Calling it after the isolate has started will cause undetermined behavior.

Parameters:

reserved - The minimum amount of memory guaranteed to be available to the isolate at any time.

total - The total amount of memory that the isolate can reserve.

setPriority

public void setPriority(int new_priority)

Adjust the priority of this Isolate. The priority controls the amount of CPU time that VM allocates to execute threads in this Isolate. Note: thread scheduling and task scheduling use separate mechanisms. In the current imeplentation, each task is guaranteed execution time relative to its priority.

Parameters:

new_priority - must be between MIN_PRIORITY and MAX_PRIORITY, or else this method call will have no effect.

getPriority

public int getPriority()

Returns the priority of this isolate.

Returns:

the priority of this isolate. If the isolate has already terminated, the returned value is undefined.

isSuspended

public boolean isSuspended()

Returns if this isolate has been suspended.

Returns:

true iff the isolate has been suspended.

suspend

public void suspend()

Suspends all threads in this isolate from execution. This method should be used carefully if objects shared between isolates (passed via native methods) are used for synchornization. A suspended isolate holding a lock on such an object will stop other tasks from ever receiving that lock. See introduction for better ways of communicating between isolates. This method will suspend the isolate only if the isolate is currently started, not suspended and not terminated. Otherwise this method has no effect.

resume

public void resume()

The opposite of the suspend method. This method will resume the isolate only if the isolate is currently started, suspended and not terminated. Otherwise this method has no effect.

exitCode

public int exitCode()

Returns the exit code of the isolate. If this Isolate has terminated, this method returns the exit code parameter to the first invocation of System.exit(), Isolate.exit() or Isolate.halt() that caused the Isolate to terminate. If this Isolate has terminated without calling System.exit(), Isolate.exit() or Isolate.halt(), then 0 is returned. If this Isolate has not started or has not terminated, 0 is returned.

Returns:

the exit code of the isolate.

waitForExit

public void waitForExit()

Blocks the execution of the calling thread until this Isolate has exited. If waitForExit() is called on the current Isolate, the result is undefined.

Throws:

InterruptedException - (unimplemented yet): if CLDC Specification 1.1 is enabled, when a thread is blocked inside this method, it may be interrupted by an invocation of Thread.interrupt, in which case an InterruptedException is thrown regardless of the termination status of this Isolate.

getClassPath

public String[] getClassPath()

Returns the classpath the Isolate was started with.

Returns:

String[] that is equal to classpath argument passed to Isolate constructor

setAPIAccess

public void setAPIAccess(boolean access)

Sets the access to Isolate API for this Isolate. This method should be used by the AMS, before the Isolate is started, to control whether or not a created Isolate is able to call the Isolate API. The default for all but the first Isolate is false. If the AMS calls this method after the Isolate has started, it has no effect.

In additional, after an Isolate has started, if it has access to the Isolate API, it can call this method to disable it. However, once it loses the access, attempts to call this method would result in a SecurityException.

setDebug

public void setDebug(boolean mode)

attachDebugger

public void attachDebugger()

isDebuggerConnected

public boolean isDebuggerConnected()

Indicates if debugger connection is established with the VM.

Returns:

true if debugger is connected, otherwise returns false.

setUseVerifier

public void setUseVerifier(boolean verify)

Controls whether or not classes for this isolate need to be verified. When creating a new Isolate, the AMS may waive verification for classes that have already been verified. The default is false. This method should be called before the Isolate is started.

setProfile

public void setProfile(String profile)
                throws IllegalArgumentException,
                       IllegalIsolateStateException

Sets active profile name for isolate. This method must be called before the isolate is started. If isolate is already started the method throws an IllegalIsolateStateException. The method also determines if profile is a name of existing profile which is defined in ROM configuration file. If not, throws runtime IllegalArgumentException.

Parameters:

profile - The new active profile name.

Throws:

IllegalArgumentException

IllegalIsolateStateException

setHiddenPackages

public void setHiddenPackages(String[] package_names)
                       throws IllegalIsolateStateException

Sets the packages which will be hidden. See definition of hidden package in doc/misc/Romizer.html. Note, that this function call overrides previous settings. If isolate is already started the method throws an IllegalIsolateStateException.

Parameters:

package_name. - The name of package for marking.

Throws:

IllegalIsolateStateException

setRestrictedPackages

public void setRestrictedPackages(String[] package_names)
                           throws IllegalIsolateStateException

Sets the packages which will be restricted. See definition of restricted package in doc/misc/Romizer.html. Note, that this function call overrides previous settings. If isolate is already started the method throws an IllegalIsolateStateException.

Parameters:

package_name - The name of package for marking.

Throws:

IllegalIsolateStateException

setUseProfiler

public void setUseProfiler(boolean useProfiler)

Sets whether isolate should be profiled or not. By default all isolates are profiled. Should be set before task for isolate is created.