SunSPOT API V3.0


com.sun.squawk
Class Isolate

java.lang.Object
  extended by com.sun.squawk.Isolate
All Implemented Interfaces:
Runnable

public final class Isolate
extends Object
implements Runnable

The Isolate class represents a "process-like" unit of computation that is isolated from other instances of Isolate. The mutable objects of one isolate are logically separate from the mutable objects of another isolate. Similarly, the static variables of one isolate are seperate from the static variables of another isolate.

A Simple Example

The following code example shows the creation of a simple isolate with a single main method argument of "test" and a default context. The created isolate simply prints its arguments array.

  // The creating isolate
  Isolate i = new Isolate("org.example.App", "test", null, Isolate.currentIsolate().getParentSuiteSourceURI());
  i.start();
  i.join(); // wait for child isolate to finish
  System.out.println("Child isolate returned with exit code: " + i.getExitCode());

  // The newly created isolate
  package org.example;

  public class App {
      public static void main(String[] args) {
          for(int i = 0; i < args.length; i++ )
              System.out.println(args[i]);
      }
  }
Note that the last two arguments to the constructor are a classpath, and a URI, which specify where the isolate's main class can be found. The classpath is used when Squawk is configured with a class TranslatorInterface, while the URI specifies the Suite which contains the translated class file org.example.App. In this example code we specified that the child isolate will use the same suite as the parent Isolate.

Hibernation

An isolate may be suspended in hibernation. Hibernation removes the isolate and all of the isolate's threads from further execution. Once an isolate is hibernated, it can be serialized using the save(DataOutputStream, String) method. The saved form of the isolate includes all reachable objects, the state of all static variables, and the current execution context of all of the isolate's threads (the thread stacks, etc). The saved form can be stored in a file, sent over a network, etc. load(DataInputStream, String) can be used reconstruct the saved isolate.

Isolate Lifecycle

An Isolate may be in one of several states: NEW, ALIVE, HIBERNATED, and EXITED. The methods isNew(), isAlive(), isHibernated(), isExited() can be used to determine an isolate's current state. An Isolate starts out in the NEW state. When the start() method is called the isolate becomes ALIVE. hibernate() causes an isolate to become HIBERNATED, while unhibernate() brings a HIBERNATED back to ALIVE. An ALIVE isolate may become EXITED by calling exit(int).

Isolate LifecycleNotification

An isolate can register listeners to be notified of changes in an isolate's lifecycle, such as hibernating, unhibernating, or exiting. An isolate can listen for it's own events, or for events on another isolate. To receive notifications of lifecycle events, create a class that implements Isolate.LifecycleListener, and register the listener using addLifecycleListener(com.sun.squawk.Isolate.LifecycleListener, int) and one or more of the lifecycle event masks (such as SHUTDOWN_EVENT_MASK). When the isolate state changes to the specified event, the system will call the listener's Isolate.LifecycleListener.handleLifecycleListenerEvent(com.sun.squawk.Isolate, int) method, passing in the appropriate isolate and event kind.

Inter-Isolate Communication

Isolates may communicate between each other using Channel and ServerChannel instances, or a parent isolate may pass arguments to the main method of the child isolate, or add properties to a child isolate be calling setProperty(String, String).

The properties parameter to the Isolate constructor provides another way to set the system properties of the new isolate. If this parameter is not specified, the child isolate starts with the same set of system properties that it would have if initiated as a standalone application. If this parameter is specified, this default set of properties is augmented with those specified in the parameter, in the same way as if they had been specified with -D on a command line invocation.

OtherDetails

Each Isolate has independent output streams for System.out and System.err. These output streams can be attached to instances of Connection by passing Generic Connection Framework URIs to addOut(String) or addErr(String).

Squawk Isolates are loosely based on the Isolates of JSR 121 - Application Isolation API, but are not compliant with that specification. In particular, Squawk Isolates support hibernation, and use a different inter-isolate communication mechanism than JSR 121.

Author:
Nik Shaylor, Doug Simon
See Also:
Channel, ServerChannel

Nested Class Summary
static interface Isolate.LifecycleListener
          Monitor isolate lifecycle events such as shutdown, hibernate, and unhibernate.
 
Field Summary
static int HIBERNATE_EVENT_MASK
          Event kind indicating that an isolate is hibernating.
static int SHUTDOWN_EVENT_MASK
          Event kind indicating that an isolate is exiting.
static int UNHIBERNATE_EVENT_MASK
          Event kind indicating that an isolate is unhibernating.
 
Constructor Summary
Isolate(Hashtable properties, int midletNum, String classPath, String parentSuiteSourceURI)
          Creates an new isolate.
Isolate(Hashtable properties, String mainClassName, String[] args, String classPath, String parentSuiteSourceURI)
          Creates an new isolate.
Isolate(String mainClassName, String[] args, String classPath, String parentSuiteSourceURI)
          Creates an new isolate.
 
Method Summary
 void addErr(String url)
          Adds a new connection to which System.err will send its output.
 void addLifecycleListener(Isolate.LifecycleListener listener, int eventSet)
          Add a listener to be run when this isolate terminates, hibernates, or unhibernates, depending on evenSet.
 void addOut(String url)
          Adds a new connection to which System.out will send its output.
 void clearErr()
          Removes all the connections to which System.err is sending its output.
 void clearOut()
          Removes all the connections to which System.out is sending its output.
static Isolate currentIsolate()
          Gets the current isolate context.
 void exit(int code)
          Stop the isolate.
 String getClassPath()
          Gets the class path for the isolate.
 int getExitCode()
          Get the isolate exit code.
 int getId()
          Gets the unique id for this isolate.
static Isolate[] getIsolates()
          Returns an array of Isolate objects.
 String[] getMainClassArguments()
          Get the arguments.
 String getMainClassName()
          Get the name of the main class.
 String getParentSuiteSourceURI()
           
 String getProperty(String key)
          Gets a named property of this isolate.
 void hibernate()
          Hibernate the isolate.
 String intern(String value)
          Returns a canonical representation for the string object.
 boolean isAlive()
          Determines if this isolate has been (re)started and not yet (re)hibernated or exited.
 boolean isBeingDebugged()
          Determines whether this isolate is being debugged
 boolean isExited()
          Determines if this isolate is exited.
 boolean isHibernated()
          Determines if this isolate is hibernated.
 boolean isMidlet()
          Return true if this isolate was created to run a midlet.
 boolean isNew()
          Determines if this isolate has not yet been started.
 boolean isTrusted()
          Determines if this isolate can access trusted classes.
 void join()
          Waits for all the other threads and child isolates belonging to this isolate to stop.
 String[] listErr()
          Gets a list of URLs denoting the streams to which System.err is currently sending its output.
 String[] listOut()
          Gets a list of URLs denoting the streams to which System.out is currently sending its output.
static Isolate load(DataInputStream dis, String uri)
          Loads a serialized isolate from an input stream into RAM.
 void removeErr(String url)
          Removes the connection identified by url (if any) to which System.err is currently sending its output.
 boolean removeLifecycleListener(Isolate.LifecycleListener listener, int eventSet)
          Remove an Isolate.LifecycleListener from this isolate.
 void removeOut(String url)
          Removes the connection identified by url (if any) to which System.out is currently sending its output.
 void run()
          Deprecated. This is called by the system (in start()}, and shouldn't be called directly
 void save(DataOutputStream dos, String uri)
          Serializes the object graph rooted by this hibernated isolate and writes it to a given stream.
 void save(DataOutputStream dos, String uri, boolean bigEndian)
          Serializes the object graph rooted by this hibernated isolate and writes it to a given stream.
 void setProperty(String key, String value)
          Adds a named property to this isolate.
 void start()
          Start the isolate running.
 String toString()
          Get the string representation of the isolate.
 void unhibernate()
          Unhibernate the isolate.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

HIBERNATE_EVENT_MASK

public static final int HIBERNATE_EVENT_MASK
Event kind indicating that an isolate is hibernating. Used for Isolate.LifecycleListeners that will be called when the Isolate suspends via hibernate().

See Also:
Constant Field Values

SHUTDOWN_EVENT_MASK

public static final int SHUTDOWN_EVENT_MASK
Event kind indicating that an isolate is exiting. Used for Isolate.LifecycleListeners that will be called when the Isolate terminates via exit(int), VM.stopVM(int), or when the last non-daemon thread in this isolate ends. All other ways to terminate an isolate, including VM.haltVM(int) do not cause the shutdown hooks to be run.

See Also:
Constant Field Values

UNHIBERNATE_EVENT_MASK

public static final int UNHIBERNATE_EVENT_MASK
Event kind indicating that an isolate is unhibernating. Used for Isolate.LifecycleListeners that will be called when the Isolate resumes via unhibernate().

See Also:
Constant Field Values
Constructor Detail

Isolate

public Isolate(String mainClassName,
               String[] args,
               String classPath,
               String parentSuiteSourceURI)
Creates an new isolate. start() will create a new execution context, and start executing the main method of the class specified by mainClassName.

Parameters:
mainClassName - the name of the class with main()
args - the command line arguments
classPath - the path where classes and suites can be found (may be null)
parentSuiteSourceURI - the URI of the suite containing mainClassName. (may be null)
Throws:
NullPointerException - if mainClassName or args is null

Isolate

public Isolate(Hashtable properties,
               int midletNum,
               String classPath,
               String parentSuiteSourceURI)
Creates an new isolate. start() will create a new execution context, and start executing the startApp method of the MIDlet specified by the manifest property named MIDlet-midletNum. System properties can be set for the isolate by passing in a hashtable where the keys are strings of property names and the values are strings containing property values.

Note that system properties are disjoint from manifest properties.

Parameters:
properties - a hashtable of properties to be set in the isolate (may be null)
midletNum - the midlet property that contains the name of the MIDlet to instantiate
classPath - the path where classes and suites can be found (may be null)
parentSuiteSourceURI - the URI of the suite containing the midlet and the MIDlet properties. (may be null)
Throws:
NullPointerException - if mainClassName or args is null
ClassCastException - if properties contains keys or values that are not Strings.

Isolate

public Isolate(Hashtable properties,
               String mainClassName,
               String[] args,
               String classPath,
               String parentSuiteSourceURI)
Creates an new isolate. start() will create a new execution context, and start executing the main method of the class specified by mainClassName. System properties can be set for the isolate by passing in a hashtable where the keys are strings of property names and the values are strings containing property values.

Note that system properties are disjoint from manifest properties.

Parameters:
properties - a hashtable of properties to be set in the isolate (may be null)
mainClassName - the name of the class with main()
args - the command line arguments
classPath - the path where classes and suites can be found (may be null)
parentSuiteSourceURI - the URI of the suite containing mainClassName. (may be null)
Throws:
NullPointerException - if mainClassName or args is null
ClassCastException - if properties contains keys or values that are not Strings.
Method Detail

addErr

public void addErr(String url)
Adds a new connection to which System.err will send its output.

If the current thread is not owned by this isolate, opening of the connection is delayed until the next time System.err is written to by one of this isolate's threads. Otherwise the connection is opened as part of this call.

Output will be multicast to the new stream as well as any preexisting connection streams.

Parameters:
url - the URL used to open the connection via Connector.openOutputStream(java.lang.String)
See Also:
listErr(), removeErr(java.lang.String), clearErr()

addLifecycleListener

public void addLifecycleListener(Isolate.LifecycleListener listener,
                                 int eventSet)
Add a listener to be run when this isolate terminates, hibernates, or unhibernates, depending on evenSet.

The listener may listen to multiple events by using bitwise OR to construct a set of events from the various event masks.

This isolate may be the current isolate (the local case) or another isolate (the remote case). If this isolate is remote, then this method will also add a listener to the local isolate that will remove this listener on the remote isolate. This cleans up the listeners if the local isolate exits before the remote isolate does.

Execution:

The listener will run in the current Isolate's context. All listener from the same Isolate may run in the same thread. Any RuntimeExceptions thrown by the listener will be printed to System.err, but are otherwise ignored.

Parameters:
listener - a LifecycleListener that will be called when event occurs.
eventSet - a set of lifecycle events to be monitored. One or more of SHUTDOWN_EVENT_MASK, HIBERNATE_EVENT_MASK, or UNHIBERNATE_EVENT_MASK.
Throws:
IllegalArgumentException - when eventSet does not contain SHUTDOWN_EVENT_MASK, HIBERNATE_EVENT_MASK, or UNHIBERNATE_EVENT_MASK
See Also:
removeLifecycleListener(com.sun.squawk.Isolate.LifecycleListener, int), exit(int), hibernate(), unhibernate()

addOut

public void addOut(String url)
Adds a new connection to which System.out will send its output.

If the current thread is not owned by this isolate, opening of the connection is delayed until the next time System.out is written to by one of this isolate's threads. Otherwise the connection is opened as part of this call.

Output will be multicast to the new stream as well as any preexisting connection streams.

The following code snippet is an example of how to pipe the standard output of the current isolate to a network connection:

     Thread.currentThread().getIsolate().addOut("socket://server.domain.com:9999").
 

Parameters:
url - the URL used to open the connection via Connector.openOutputStream(java.lang.String)
See Also:
listOut(), removeOut(java.lang.String), clearOut()

clearErr

public void clearErr()
Removes all the connections to which System.err is sending its output. The removed connections are immediately flushed and closed. Any IO exceptions are caught and are unlikely to be printed.

See Also:
addErr(java.lang.String), removeErr(java.lang.String)

clearOut

public void clearOut()
Removes all the connections to which System.out is sending its output. The removed connections are immediately flushed and closed.. Any IO exceptions are caught and might be printed.

See Also:
addOut(java.lang.String), removeOut(java.lang.String)

currentIsolate

public static Isolate currentIsolate()
Gets the current isolate context.

Returns:
the current Isolate context.

exit

public void exit(int code)
Stop the isolate. The handleLifecycleListenerEvent() method will be called on any LifecycleListeners registered to handle EXIT events on this isolate.

Parameters:
code - the exit code
Throws:
IllegalStateException - if this isolate is not ALIVE

getClassPath

public String getClassPath()
Gets the class path for the isolate.

Returns:
the class path

getExitCode

public int getExitCode()
Get the isolate exit code.

Returns:
the exit code

getId

public int getId()
Gets the unique id for this isolate. The id is only unique among isolates that have allocated in the current run of this VM.

Returns:
the id of this isolate

getIsolates

public static Isolate[] getIsolates()
Returns an array of Isolate objects. The array contains one entry for each isolate object that is currently reachable in the system. These isolates may be in the NEW, ALIVE, HIBERNATED, or EXITED states. The system only keeps ALIVE isolates reachable, so isolates in other states may become unreachable unless referenced by an ALIVE isolate. New isolates may have been constructed or existing ones terminated by the time method returns.

Returns:
the Isolate objects present at the time of the call

getMainClassArguments

public String[] getMainClassArguments()
Get the arguments.

Returns:
the arguments

getMainClassName

public String getMainClassName()
Get the name of the main class.

Returns:
the name

getParentSuiteSourceURI

public String getParentSuiteSourceURI()
Returns:
the URI of suite from which this isolate was started. This value will be "memory:bootstrap" if the isolate was not given an explicit suite at creation time.

getProperty

public String getProperty(String key)
Gets a named property of this isolate.

Parameters:
key - the name of the property to get
Returns:
the value of the property named by 'key' or null if there is no such property

hibernate

public void hibernate()
               throws IOException,
                      IllegalStateException
Hibernate the isolate. The handleLifecycleListenerEvent() method will be called on any LifecycleListeners registered to handle HIBERNATE events on this isolate. Any Channel I/O will be hibernated, and interisolate communication channels will be broken. If the current thread is in this isolate then this function will only return when the isolate is unhibernated.

Throws:
IOException - if the underlying IO system cannot be serialized
IllegalStateException - if this isolate is not ALIVE or if it has a debugger attached to it

intern

public String intern(String value)
Returns a canonical representation for the string object.

A pool of strings, initially empty, is maintained privately by the class Isolate.

When the intern method is invoked, if the pool already contains a string equal to this String object as determined by the Object.equals(Object) method, then the string from the pool is returned. Otherwise, this String object is added to the pool and a reference to this String object is returned.

It follows that for any two strings s and t, s.intern() == t.intern() is true if and only if s.equals(t) is true.

All literal strings and string-valued constant expressions are interned. String literals are defined in §3.10.5 of the Java Language Specification

Returns:
a string that has the same contents as this string, but is guaranteed to be from a pool of unique strings.

isAlive

public boolean isAlive()
Determines if this isolate has been (re)started and not yet (re)hibernated or exited.

Returns:
true if it is

isBeingDebugged

public boolean isBeingDebugged()
Determines whether this isolate is being debugged

Returns:
true if it is

isExited

public boolean isExited()
Determines if this isolate is exited.

Returns:
true if it is

isHibernated

public boolean isHibernated()
Determines if this isolate is hibernated.

Returns:
true if it is

isMidlet

public boolean isMidlet()
Return true if this isolate was created to run a midlet.


isNew

public boolean isNew()
Determines if this isolate has not yet been started.

Returns:
true if it is

isTrusted

public boolean isTrusted()
Determines if this isolate can access trusted classes. A trusted class will call this method in its static constructor.

Returns:
boolean

join

public void join()
Waits for all the other threads and child isolates belonging to this isolate to stop.


listErr

public String[] listErr()
Gets a list of URLs denoting the streams to which System.err is currently sending its output. Note that due to multi-threading, the returned list may not reflect the complete set of streams. If a stream was added by another thread, then the returned list may not include the URL of the added stream. If a stream was removed by another thread, then the returned list may include the URL of the removed stream.

Returns:
the list of streams to which System.err is currently sending its output
See Also:
addErr(java.lang.String)

listOut

public String[] listOut()
Gets a list of URLs denoting the streams to which System.out is currently sending its output. Note that due to multi-threading, the returned list may not reflect the complete set of streams. If a stream was added by another thread, then the returned list may not include the URL of the added stream. If a stream was removed by another thread, then the returned list may include the URL of the removed stream.

Returns:
the list of streams to which System.out is currently sending its output
See Also:
addOut(java.lang.String)

load

public static Isolate load(DataInputStream dis,
                           String uri)
Loads a serialized isolate from an input stream into RAM. It is up to the caller to unhibernate the isolate.

Parameters:
dis - the data input stream to load from
uri - a URI identifying the serialized isolate

removeErr

public void removeErr(String url)
Removes the connection identified by url (if any) to which System.err is currently sending its output. The removed connection is immediately flushed and closed. Any IO exceptions are caught and might be printed.

Parameters:
url - the URL identifying the connection to be removed
See Also:
listErr(), addErr(java.lang.String), clearErr()

removeLifecycleListener

public boolean removeLifecycleListener(Isolate.LifecycleListener listener,
                                       int eventSet)
Remove an Isolate.LifecycleListener from this isolate. Must be called from the same isolate that added the listener.

Parameters:
listener - a Isolate.LifecycleListener to be removed.
eventSet - a set of lifecycle events that the listener should stop listening to. One or more of SHUTDOWN_EVENT_MASK, HIBERNATE_EVENT_MASK, or UNHIBERNATE_EVENT_MASK.
Returns:
true if the listener was registered with the all of the events in the eventSet on this isolate; false otherwise.
Throws:
IllegalArgumentException - when eventSet does not contain SHUTDOWN_EVENT_MASK, HIBERNATE_EVENT_MASK, or UNHIBERNATE_EVENT_MASK
See Also:
addLifecycleListener(com.sun.squawk.Isolate.LifecycleListener, int)

removeOut

public void removeOut(String url)
Removes the connection identified by url (if any) to which System.out is currently sending its output. The removed connection is immediately flushed and closed. Any IO exceptions are caught and might be printed.

Parameters:
url - the URL identifying the connection to be removed
See Also:
listOut(), addOut(java.lang.String), clearOut()

run

public final void run()
               throws IllegalStateException
Deprecated. This is called by the system (in start()}, and shouldn't be called directly

Starts running this isolate.

Specified by:
run in interface Runnable
Throws:
IllegalStateException - if this isolate has already been started
See Also:
Thread.run()

save

public void save(DataOutputStream dos,
                 String uri)
          throws IOException
Serializes the object graph rooted by this hibernated isolate and writes it to a given stream. The endianess of the serialized object graph is the endianess of the unerdlying platform.

Parameters:
dos - the DataOutputStream to which the serialized isolate should be written
uri - a URI identifying the serialized isolate
Throws:
OutOfMemoryError - if there was insufficient memory to do the save
IOException - if there was some IO problem while writing the output
IllegalStateException - if this isolate is not currently hibernated or exited

save

public void save(DataOutputStream dos,
                 String uri,
                 boolean bigEndian)
          throws IOException
Serializes the object graph rooted by this hibernated isolate and writes it to a given stream.

Parameters:
dos - the DataOutputStream to which the serialized isolate should be written
uri - a URI identifying the serialized isolate
bigEndian - the endianess to be used when serializing this isolate
Throws:
OutOfMemoryError - if there was insufficient memory to do the save
IOException - if there was some IO problem while writing the output
IllegalStateException - if this isolate is not currently hibernated or exited

setProperty

public void setProperty(String key,
                        String value)
Adds a named property to this isolate. These properties are included in the look up performed by System.getProperty(String).

Parameters:
key - the name of the property
value - the value of the property or null to remove the property

start

public void start()
Start the isolate running.

Throws:
IllegalStateException - if the isolate has already been started

toString

public String toString()
Get the string representation of the isolate.

Overrides:
toString in class Object
Returns:
the string

unhibernate

public void unhibernate()
Unhibernate the isolate. The handleLifecycleListenerEvent() method will be called on any LifecycleListeners registered to handle UNHIBERNATE events on this isolate.

Throws:
IllegalStateException - if the isolate is not HIBERNATED

SunSPOT API V3.0


Copyright © 2006, 2007 Sun Microsystems, Inc. All Rights Reserved.