com.sun.squawk
Class Isolate

java.lang.Object
  com.sun.squawk.Isolate

All Implemented Interfaces:

Runnable

public final class Isolate
extends Object
implements Runnable

The Squawk implementation of isolates.

Author:

Nik Shaylor, Doug Simon

Nested Class Summary

static class	Isolate.Breakpoint A Breakpoint instance describes a point in a method at which a breakpoint has been set.
static class	Isolate.Message
static class	Isolate.Parcel A Parcel encapsulates a Isolate.Message posted to an isolate and contains a reference to the sending isolate.

Field Summary

MulticastOutputStream	stderr
MulticastOutputStream	stdout

Constructor Summary

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	addOut(String url) Adds a new connection to which System.out will send its output.
void	cleanupMailboxes() Tell remote isolates that we won't talk to them again, and close our Mailboxes.
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.
void	forgetMailbox(Mailbox mailbox) Tell the system to forget about this mailbox.
void	forgetMailboxAddress(MailboxAddress address) Tell the system to forget about this mailbox.
int	getChildThreadCount() Gets the number of child threads of this isolate.
Enumeration	getChildThreads() Gets the child threads of this isolate.
String	getClassPath() Gets the class path for the isolate.
Debugger	getDebugger() Gets the debugger under which this isolate is executing.
int	getExitCode() Get the isolate exit code.
static Isolate[]	getIsolates() Returns an array of active Isolate objects.
Suite	getLeafSuite() Gets the suite that is the starting point for class lookup in this isolate.
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.
TranslatorInterface	getTranslator() Gets a translator that is to be used to locate, load and convert classes that are not currently installed in this isolate's runtime environment.
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	isClassKlassInitialized() Test to see if class Klass is initialized.
boolean	isExited() Determines if this isolate is exited.
boolean	isHibernated() Determines if this isolate is hibernated.
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.
static Isolate.Parcel	receiveMessage(Isolate from) Retrieves the next available message sent to this isolate, blocking until a message is available.
void	recordMailbox(Mailbox mailbox) Record this mailbox with the system.
void	recordMailboxAddress(MailboxAddress address) Record all MailboxAddress objects that this Isolate uses to send messages to.
void	removeErr(String url) Removes the connection identified by url (if any) to which System.err is currently sending its output.
void	removeOut(String url) Removes the connection identified by url (if any) to which System.out is currently sending its output.
void	run() Starts running this isolate.
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.
static void	sendMessage(Isolate to, Isolate.Message message)
void	setProperty(String key, String value) Adds a named property to this isolate.
void	start() Start the isolate.
String	toString() Get the string representation of the isolate.
void	unhibernate() Unhibernate the isolate.
void	updateBreakpoints(Isolate.Breakpoint[] breakpoints)

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

stdout

public final MulticastOutputStream stdout

stderr

public final MulticastOutputStream stderr

Constructor Detail

Isolate

public Isolate(String mainClassName,
               String[] args,
               String classPath,
               String parentSuiteSourceURI)

Creates an new isolate.

Parameters:

mainClassName - the name of the class with main()

args - the command line arguments

classPath - the path where classes and suites can be found

parentSuiteSourceURI -

Throws:

NullPointerException - if mainClassName or args is null

Method Detail

getClassPath

public String getClassPath()

Gets the class path for the isolate.

Returns:

the class path

getIsolates

public static Isolate[] getIsolates()

Returns an array of active Isolate objects. The array contains one entry for each isolate in the invoker's aggregate that has been started but has not yet terminated. New isolates may have been constructed or existing ones terminated by the time method returns.

Returns:

the active Isolate objects present at the time of the call

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.

getMainClassName

public String getMainClassName()

Get the name of the main class.

Returns:

the name

currentIsolate

public static Isolate currentIsolate()

Gets the current isolate context.

Returns:

the current Isolate context.

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

getMainClassArguments

public String[] getMainClassArguments()

Get the arguments.

Returns:

the arguments

getLeafSuite

public Suite getLeafSuite()

Gets the suite that is the starting point for class lookup in this isolate. If it is not closed, then it's also the suite into which any dynamically loaded classes (i.e. those loaded via Class.forName(String)) are installed.

Returns:

the leaf suite

getTranslator

public TranslatorInterface getTranslator()
                                  throws IllegalThreadStateException

Gets a translator that is to be used to locate, load and convert classes that are not currently installed in this isolate's runtime environment.

Returns:

a translator for installing new classes or null if the system does not support dynamic class loading

Throws:

IllegalThreadStateException

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

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

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.

start

public void start()

Start the isolate.

run

public final void run()
               throws IllegalStateException

Starts running this isolate.

Specified by:

run in interface Runnable

Throws:

IllegalStateException - if this isolate has already been started

See Also:

Thread.run()

join

public void join()

Waits for all the other threads and child isolates belonging to this isolate to stop.

isClassKlassInitialized

public boolean isClassKlassInitialized()

Test to see if class Klass is initialized.

Returns:

true if it is

exit

public void exit(int code)

Stop the isolate.

Parameters:

code - the exit code

Throws:

IllegalStateException - if this isolate has not yet been started or is already hibernated or exited

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

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

hibernate

public void hibernate()
               throws IOException,
                      IllegalStateException

Hibernate the isolate. 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 has not yet been started or is already hibernated or exited or has a debugger attached to it

unhibernate

public void unhibernate()

Unhibernate the isolate.

isHibernated

public boolean isHibernated()

Determines if this isolate is hibernated.

Returns:

true if it is

isAlive

public boolean isAlive()

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

Returns:

true if it is

isExited

public boolean isExited()

Determines if this isolate is exited.

Returns:

true if it is

isNew

public boolean isNew()

Determines if this isolate has not yet been started.

Returns:

true if it is

isBeingDebugged

public boolean isBeingDebugged()

Determines whether this isolate is being debugged

Returns:

true if it is

getExitCode

public int getExitCode()

Get the isolate exit code.

Returns:

the exit code

toString

public String toString()

Get the string representation of the isolate.

Overrides:

toString in class Object

Returns:

the string

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.

If there was an existing connection identified by url prior to this call, it is replaced and will rely on finalization for being closed.

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)

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.

If there was an existing connection identified by url prior to this call, it is replaced and will rely on finalization for being closed.

Parameters:

url - the URL used to open the connection via Connector.openOutputStream(java.lang.String)

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 relies upon finalization for releasing any system resources it holds.

Parameters:

url - the URL identifying the connection to be removed

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 relies upon finalization for releasing any system resources it holds.

Parameters:

url - the URL identifying the connection to be removed

clearOut

public void clearOut()

Removes all the connections to which System.out is sending its output. The removed connections rely upon finalization for releasing any system resources they hold.

clearErr

public void clearErr()

Removes all the connections to which System.err is sending its output. The removed connections rely upon finalization for releasing any system resources they hold.

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

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

recordMailbox

public void recordMailbox(Mailbox mailbox)

Record this mailbox with the system. Called by Mailbox().

Parameters:

mailbox - the mailbox to record.

forgetMailbox

public void forgetMailbox(Mailbox mailbox)

Tell the system to forget about this mailbox. Called by Mailbox.close().

Parameters:

mailbox - the mailbox to forget.

recordMailboxAddress

public void recordMailboxAddress(MailboxAddress address)

Record all MailboxAddress objects that this Isolate uses to send messages to.

Parameters:

mailbox - the mailbox to record.

forgetMailboxAddress

public void forgetMailboxAddress(MailboxAddress address)

Tell the system to forget about this mailbox. Called by Mailbox.close().

Parameters:

mailbox - the mailbox to forget.

cleanupMailboxes

public void cleanupMailboxes()

Tell remote isolates that we won't talk to them again, and close our Mailboxes. After this call, remote isolates may have MailboxAddress objects that refer to the closed mailboxes, but when they try to use the address, they will get an exception.

sendMessage

public static void sendMessage(Isolate to,
                               Isolate.Message message)

receiveMessage

public static Isolate.Parcel receiveMessage(Isolate from)

Retrieves the next available message sent to this isolate, blocking until a message is available. Once a message has been retrieved, it is removed from the receiving isolate's inbox.

Parameters:

from - if not null, only a message sent by from will be returned

Returns:

the retrieved message

getDebugger

public Debugger getDebugger()

Gets the debugger under which this isolate is executing.

Returns:

the debugger under which this isolate is executing (if any)

getChildThreads

public Enumeration getChildThreads()

Gets the child threads of this isolate.

Returns:

an Enumeration over the child threads of this isolate

getChildThreadCount

public int getChildThreadCount()

Gets the number of child threads of this isolate.

Returns:

the number of child threads of this isolate

updateBreakpoints

public void updateBreakpoints(Isolate.Breakpoint[] breakpoints)