Java Doc for Isolate.java in  » 6.0-JDK-Modules » j2me » com » sun » cldc » isolate » Java Source Code / Java DocumentationJava Source Code and Java Documentation

---

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

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

---

Terminology

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

• 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.

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.

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

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

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);
 }
 } 

No exception is thrown if this isolate is already terminated.

This constructor has the same effect as invoking Isolate.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
Parameters:
  mainArgs - the arguments of the main method in the new isolate
throws:
  IsolateStartupException - if an error occurs in the configurationor startup of the new isolate before any application code is invoked

This constructor has the same effect as invoking Isolate.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
Parameters:
  mainArgs - the arguments of the main method in the new isolate
Parameters:
  app_classpath - the application classpath(s) for the isolate(see Class path)
throws:
  IsolateStartupException - if an error occurs in the configurationor startup of the new isolate before any application code is invoked

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 Isolate.start start method is invoked. The Isolate.halt halt and Isolate.exit exit methods will fail if before Isolate.start 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
Parameters:
  mainArgs - the arguments of the main method in the new isolate
Parameters:
  app_classpath - the application classpath(s) for the isolate
Parameters:
  sys_classpath - the system classpath(s) for the isolate(see Class path)
throws:
  IsolateStartupException - if an error occurs in the configurationof the new isolate before any application code is invoked
throws:
  IllegalArgumentException - if any parameters are found to beinvalid.

This method never returns null. the Isolate object for the current task

No exception is thrown if this isolate is already terminated. Even if Isolate.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 Isolate.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.

No exception is thrown if this isolate is already terminated. Even if Isolate.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 Isolate.start() would result in an IsolateStartupException.

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

Implementation Note

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.

Parameters:
  reserved - The minimum amount of memory guaranteed to beavailable to the isolate at any time. Also the totalamount of memory that the isolate can reserve.

Parameters:
  reserved - The minimum amount of memory guaranteed to beavailable to the isolate at any time.
Parameters:
  total - The total amount of memory that the isolate canreserve.

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 theinitialization or configuration of the new isolatebefore any application code is invoked, or if thisIsolate was already started or is terminated.
throws:
  IsolateResourceError - if systems exceeds maximum Isolate count
throws:
  OutOfMemoryError - if the reserved memory cannot be allocated

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