flash.tools.debugger

Interface Session

All Known Implementing Classes:

PlayerSession, ThreadSafeSession

public interface Session

The Session object manages all aspects of debugging session with the Flash Player. A program can be suspended, resumed, single stepping can be performed and state information can be obtained through this object.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	bind() Allow the session to start communicating with the player.
void	breakOnCaughtExceptions(boolean b) The player always halts on exceptions that are not going to be caught; this call allows the debugger to control its behavior when an exception that *will* be caught is thrown.
Value	callConstructor(String classname, Value[] args) Invokes a constructor in the player.
Value	callFunction(Value thisObject, String functionName, Value[] args) Invokes a function.
Location	clearBreakpoint(Location location) Remove a breakpoint at given location.
boolean	clearExceptionBreakpoint(String exceptionClass) Clears an exception breakpoint.
Watch	clearWatch(Watch watch) Remove a previously created watchpoint.
Value	evalAs(Value value, Value type) Evaluate the ActionScript expression "value as type"
boolean	evalIn(Value property, Value object) Evaluate the ActionScript expression "property in object"
boolean	evalInstanceof(Value value, String type) Evaluate the ActionScript expression "value instanceof type"
boolean	evalInstanceof(Value value, Value type) Evaluate the ActionScript expression "value instanceof type"
boolean	evalIs(Value value, String type) Evaluate the ActionScript expression "value is type"
boolean	evalIs(Value value, Value type) Evaluate the ActionScript expression "value is type"
Location[]	getBreakpointList() Get a list of the current breakpoints.
Exception	getDisconnectCause() Returns the root SocketException that caused the rxMessage() thread to shut down.
int	getEventCount() Returns the number of events currently in the queue.
Frame[]	getFrames() Returns an array of frames that identify the location and contain arguments, locals and 'this' information for each frame on the function call stack.
Value	getGlobal(String name) Looks up a global name, like "MyClass", "String", etc.
Process	getLaunchProcess() Returns the Process object, if any, that triggered this Session.
int	getPreference(String pref) Return the value of a particular preference item
SourceLocator	getSourceLocator() Gets the SourceLocator for this session.
SwfInfo[]	getSwfs() Obtain information about the various SWF(s) that have been loaded into the Player, for this session.
String	getURI() Returns the URL that identifies this Session.
Value	getValue(long valueId) From a given value identifier return a Value.
Variable[]	getVariableList() Deprecated. As of version 2.
Watch[]	getWatchList() Get a list of the current watchpoint.
Isolate[]	getWorkers() Get an array of all workers that the debugger knows of.
IsolateSession	getWorkerSession(int isolateId) Return the worker specific session object that can be used to communicate with that worker.
boolean	isConnected() Is the Player currently connected for this session.
boolean	isSuspended() Is the Player currently halted awaiting requests, such as continue, stepOut, stepIn, stepOver.
DebugEvent	nextEvent() Removes and returns the next event from queue
Isolate[]	refreshWorkers() Ask the player again for a list of all workers.
void	resume() Continue a halted session.
Location	setBreakpoint(int fileId, int lineNum) Set a breakpoint on a line within the given file.
boolean	setExceptionBreakpoint(String exceptionClass) Set an exception breakpoint.
void	setLauncher(ILauncher launcher) Sets the ILauncher instance which is associated with this session.
void	setPreference(String pref, int value) Adjust the preferences for this session; see SessionManager for a list of valid preference strings.
void	setSourceLocator(SourceLocator sourceLocator) Sets the SourceLocator for this session.
Watch	setWatch(Value v, String memberName, int kind) Set a watchpoint on a given variable.
Watch	setWatch(Watch watch) Enables or disables a watchpoint.
void	stepContinue() Continue the process of stepping.
void	stepInto() Step to the next executable source line within the program, will enter into functions.
void	stepOut() Step out of the current method/function onto the next executable soruce line.
void	stepOver() Step to the next executable source line within the program, will NOT enter into functions.
boolean	supportsConcurrency() Returns whether the target player supports concurrency.
boolean	supportsWatchpoints() Returns whether the target player supports watchpoints.
void	suspend() Halt a running session.
int	suspendReason() Returns a SuspendReason integer which indicates why the Player has suspended execution.
void	terminate() Permanently stops the debugging session and breaks the connection.
void	unbind() Permanently stops the debugging session and breaks the connection.
void	waitForEvent() Events provide a mechanism whereby status information is provided from the Player in a timely fashion.

Method Detail

getURI

String getURI()

Returns the URL that identifies this Session. Note: this may not be unique across Sessions if the same launching mechanism and SWF are used.

Returns:

URI received from the connected Player. It identifies the debugging session

getLaunchProcess

Process getLaunchProcess()

Returns the Process object, if any, that triggered this Session.

Returns:

the Process object that was used to create this Session. If SessionManager.launch() was not used, then null is returned.

setPreference

void setPreference(String pref,
                 int value)

Adjust the preferences for this session; see SessionManager for a list of valid preference strings. If an invalid preference is passed, it will be silently ignored.

Parameters:

pref - preference name, one of the strings listed above

value - value to set for preference

getPreference

int getPreference(String pref)
                  throws NullPointerException

Return the value of a particular preference item

Parameters:

pref - preference name, one of the strings listed in SessionManager

Throws:

NullPointerException - if pref does not exist

See Also:

SessionManager

isConnected

boolean isConnected()

Is the Player currently connected for this session. This function must be thread-safe.

Returns:

true if connection is alive

bind

boolean bind()
             throws VersionException

Allow the session to start communicating with the player. This call must be made PRIOR to any other Session method call.

Returns:

true if bind was successful.

Throws:

VersionException - connected to Player which does not support all API completely

unbind

void unbind()

Permanently stops the debugging session and breaks the connection. If this Session is used for any subsequent calls exceptions will be thrown.

Note: this method allows the caller to disconnect from the debugging session (and Player) without terminating the Player. A subsequent call to terminate() will destroy the Player process.

Under normal circumstances this method need not be called since a call to terminate() performs both actions of disconnecting from the Player and destroying the Player process.

terminate

void terminate()

Permanently stops the debugging session and breaks the connection. If this session ID is used for any subsequent calls exceptions will be thrown.

Note that due to platform and browser differences, it should not be assumed that this function will necessarily kill the process being debugged. For example:

• On all platforms, Firefox cannot be terminated. This is because when we launch a new instance of Firefox, Firefox actually checks to see if there is another already-running instance. If there is, then the new instance just passes control to that old instance. So, the debugger doesn't know the process ID of the browser. It would be bad to attempt to figure out the PID and then kill that process, because the user might have other browser windows open that they don't want to lose.
• On Mac, similar problems apply to the Safari and Camino browsers: all browsers are launched with /usr/bin/open, so we never know the process ID, and we can't kill it. However, for Safari and Camino, what we do attempt to do is communicate with the browser via AppleScript, and tell it to close the window of the program that is being debugged.

If SessionManager.launch() was used to initiate the Session then calling this function also causes getLaunchProcess().destroy() to be called.

Note: this method first calls unbind() if needed.

resume

void resume()
            throws NotSuspendedException,
                   NotConnectedException,
                   NoResponseException

Continue a halted session. Execution of the ActionScript will commence until a reason for halting exists. That is, a breakpoint is reached or the suspend() method is called.

This method will NOT block. It will return immediately after the Player resumes execution. Use the isSuspended method to determine when the Player has halted.

Throws:

NoResponseException - if times out

NotSuspendedException - if Player is already running

NotConnectedException - if Player is disconnected from Session

suspend

void suspend()
             throws SuspendedException,
                    NotConnectedException,
                    NoResponseException

Halt a running session. Execution of the ActionScript will stop at the next possible breakpoint.

This method WILL BLOCK until the Player halts for some reason or an error occurs. During this period, one or more callbacks may be initiated.

Throws:

NoResponseException - if times out

SuspendedException - if Player is already suspended

NotConnectedException - if Player is disconnected from Session

isSuspended

boolean isSuspended()
                    throws NotConnectedException

Is the Player currently halted awaiting requests, such as continue, stepOut, stepIn, stepOver. This function is guaranteed to be thread-safe.

Returns:

true if player halted

Throws:

NotConnectedException - if Player is disconnected from Session

suspendReason

int suspendReason()
                  throws NotConnectedException

Returns a SuspendReason integer which indicates why the Player has suspended execution.

Returns:

see SuspendReason

Throws:

NotConnectedException - if Player is disconnected from Session

getFrames

Frame[] getFrames()
                  throws NotConnectedException

Returns an array of frames that identify the location and contain arguments, locals and 'this' information for each frame on the function call stack. The 0th frame contains the current location and context for the actionscript program. Likewise getFrames[getFrames().length] is the topmost (or outermost) frame of the call stack.

Returns:

array of call frames with 0th element representing the current frame.

Throws:

NotConnectedException - if Player is disconnected from Session

stepInto

void stepInto()
              throws NotSuspendedException,
                     NoResponseException,
                     NotConnectedException

Step to the next executable source line within the program, will enter into functions.

This method will NOT block. It will return immediately after the Player resumes execution. Use the isSuspended method to determine when the Player has halted.

Throws:

NoResponseException - if times out

NotSuspendedException - if Player is running

NotConnectedException - if Player is disconnected from Session

stepOut

void stepOut()
             throws NotSuspendedException,
                    NoResponseException,
                    NotConnectedException

Step out of the current method/function onto the next executable soruce line.

This method will NOT block. It will return immediately after the Player resumes execution. Use the isSuspended method to determine when the Player has halted.

Throws:

NoResponseException - if times out

NotSuspendedException - if Player is running

NotConnectedException - if Player is disconnected from Session

stepOver

void stepOver()
              throws NotSuspendedException,
                     NoResponseException,
                     NotConnectedException

Step to the next executable source line within the program, will NOT enter into functions.

This method will NOT block. It will return immediately after the Player resumes execution. Use the isSuspended method to determine when the Player has halted.

Throws:

NoResponseException - if times out

NotSuspendedException - if Player is running

NotConnectedException - if Player is disconnected from Session

stepContinue

void stepContinue()
                  throws NotSuspendedException,
                         NoResponseException,
                         NotConnectedException

Continue the process of stepping. This call should only be issued if a previous stepXXX() call was made and the Player suspended execution due to a breakpoint being hit. That is getSuspendReason() == SuspendReason.Break This operation can be used for assisting with the processing of conditional breakpoints.

Throws:

NoResponseException - if times out

NotSuspendedException - if Player is running

NotConnectedException - if Player is disconnected from Session

getSwfs

SwfInfo[] getSwfs()
                  throws NoResponseException

Obtain information about the various SWF(s) that have been loaded into the Player, for this session. Note: As SWFs are loaded by the Player a SwfLoadedEvent is fired. At this point, a call to getSwfInfo() will provide updated information.

Returns:

array of records describing the SWFs

Throws:

NoResponseException - if times out

getBreakpointList

Location[] getBreakpointList()
                             throws NoResponseException,
                                    NotConnectedException

Get a list of the current breakpoints. No specific ordering of the breakpoints is implied by the array.

Returns:

breakpoints currently set.

Throws:

NoResponseException - if times out

NotConnectedException - if Player is disconnected from Session

setBreakpoint

Location setBreakpoint(int fileId,
                     int lineNum)
                       throws NoResponseException,
                              NotConnectedException

Set a breakpoint on a line within the given file.

Warning: setBreakpoint() and clearBreakpoint() do not keep track of how many times they have been called for a given Location. For example, if you make two calls to setBreakpoint() for file X.as line 10, and then one call to clearBreakpoint() for that same file and line, then the breakpoint is gone. So, the caller is responsible for keeping track of whether the user has set two breakpoints at the same location.

Returns:

null if breakpoint not set, otherwise Location of breakpoint.

Throws:

NoResponseException - if times out

NotConnectedException - if Player is disconnected from Session

clearBreakpoint

Location clearBreakpoint(Location location)
                         throws NoResponseException,
                                NotConnectedException

Remove a breakpoint at given location. The Location obtain can be a clone/copy of a Location object returned from a previous call to getBreakpointList().

Warning: setBreakpoint() and clearBreakpoint() do not keep track of how many times they have been called for a given Location. For example, if you make two calls to setBreakpoint() for file X.as line 10, and then one call to clearBreakpoint() for that same file and line, then the breakpoint is gone. So, the caller is responsible for keeping track of whether the user has set two breakpoints at the same location.

Returns:

null if breakpoint was not removed.

Throws:

NoResponseException - if times out

NotConnectedException - if Player is disconnected from Session

getWatchList

Watch[] getWatchList()
                     throws NoResponseException,
                            NotConnectedException

Get a list of the current watchpoint. No specific ordering of the watchpoints is implied by the array. Also, the list may contain watchpoints that are no longer relevant due to the variable going out of scope.

Returns:

watchpoints currently set.

Throws:

NoResponseException - if times out

NotConnectedException - if Player is disconnected from Session

Since:

Version 2

setWatch

Watch setWatch(Value v,
             String memberName,
             int kind)
               throws NoResponseException,
                      NotConnectedException,
                      NotSupportedException

Set a watchpoint on a given variable. A watchpoint is used to suspend Player execution upon access of a particular variable. If the variable upon which the watchpoint is set goes out of scope, the watchpoint will NOT be automatically removed.

Specification of the variable item to be watched requires two pieces of information (similar to setScalarMember()) The Variable and the name of the particular member to be watched within the variable. For example if the watchpoint is to be applied to 'a.b.c'. First the Value for object 'a.b' must be obtained and then the call setWatch(v, "c", ...) can be issued. The watchpoint can be triggered (i.e. the Player suspended) when either a read or write (or either) occurs on the variable. If the Player is suspended due to a watchpoint being fired, then the suspendReason() call will return SuspendReason.WATCH.

Setting a watchpoint multiple times on the same variable will result in the old watchpoint being removed from the list and a new watchpoint being added to the end of the list.

Likewise, if a previously existing watchpoint is modified by specifiying a different kind variable then the old watchpoint will be removed from the list and a new watchpoint will be added to the end of the list.

Parameters:

v - the variable, upon whose member, the watch is to be placed.

varName - is the mmeber name upon which the watch should be placed. This variable name may NOT contain the dot ('.') character and MUST be a member of v.

kind - access type that will trigger the watchpoint to fire -- read, write, or read/write. See WatchKind.

Returns:

null if watchpoint was not created.

Throws:

NoResponseException - if times out

NotConnectedException - if Player is disconnected from Session

NotSupportedException - if the Player does not support watchpoints, or does not support watchpoints on this particular member (e.g. because it is a getter or a dynamic variable).

Since:

Version 2

See Also:

WatchKind

setWatch

Watch setWatch(Watch watch)
               throws NoResponseException,
                      NotConnectedException,
                      NotSupportedException

Enables or disables a watchpoint.

Parameters:

watch - the watch to enable or disable

enabled - whether to enable it or disable it

Throws:

NotSupportedException

NotConnectedException

NoResponseException

clearWatch

Watch clearWatch(Watch watch)
                 throws NoResponseException,
                        NotConnectedException

Remove a previously created watchpoint. The watchpoint that was removed will be returned upon a sucessful call.

Returns:

null if watchpoint was not removed.

Throws:

NoResponseException - if times out

NotConnectedException - if Player is disconnected from Session

Since:

Version 2

getVariableList

Variable[] getVariableList()
                           throws NotSuspendedException,
                                  NoResponseException,
                                  NotConnectedException,
                                  VersionException

Deprecated. As of version 2.

Obtains a list of variables that are local to the current halted state.

Throws:

NotSuspendedException

NoResponseException

NotConnectedException

VersionException

See Also:

Frame.getLocals(flash.tools.debugger.Session)

getValue

Value getValue(long valueId)
               throws NotSuspendedException,
                      NoResponseException,
                      NotConnectedException

From a given value identifier return a Value. This call allows tools to access a specific value whenever the Player has suspended. A Value's id is maintained for the life of the Value and is guaranteed not to change. Values that go out of scope are no longer accessible and will result in a null being returned. Also note, that scalar variables do not contain an id that can be referenced in this manner. Therefore the caller must also maintain the 'context' in which the variable was obtained. For example if a Number b exists on a, then the reference 'a.b' must be managed, as the id of 'a' will be needed to obtain the value of 'b'.

Parameters:

valueId - identifier from Value class or from a call to Value.getId()

Returns:

null, if value cannot be found or value with the specific id.

Throws:

NoResponseException - if times out

NotSuspendedException - if Player is running

NotConnectedException - if Player is disconnected from Session

getGlobal

Value getGlobal(String name)
                throws NotSuspendedException,
                       NoResponseException,
                       NotConnectedException

Looks up a global name, like "MyClass", "String", etc.

Returns:

its value, or null if the global does not exist.

Throws:

NotSuspendedException

NoResponseException

NotConnectedException

waitForEvent

void waitForEvent()
                  throws NotConnectedException,
                         InterruptedException

Events provide a mechanism whereby status information is provided from the Player in a timely fashion.

The caller has the option of either polling the event queue via nextEvent() or calling waitForEvent() which blocks the calling thread until one or more events exist in the queue.

Throws:

NotConnectedException - if Session is disconnected from Player

InterruptedException

getEventCount

int getEventCount()

Returns the number of events currently in the queue. This function is guaranteed to be thread-safe.

nextEvent

DebugEvent nextEvent()

Removes and returns the next event from queue

getSourceLocator

SourceLocator getSourceLocator()

Gets the SourceLocator for this session. If none has been specified, returns null.

setSourceLocator

void setSourceLocator(SourceLocator sourceLocator)

Sets the SourceLocator for this session. This can be used in order to override the default rules used for finding source files.

callConstructor

Value callConstructor(String classname,
                    Value[] args)
                      throws PlayerDebugException

Invokes a constructor in the player. Returns the newly created object. Not supported in Player 9 or AIR 1.0. If you call this function and the player to which you are connected doesn't support this feature, this will throw a PlayerDebugException.

Throws:

PlayerDebugException

callFunction

Value callFunction(Value thisObject,
                 String functionName,
                 Value[] args)
                   throws PlayerDebugException

Invokes a function. For example, calling callFunction(myobj, "toString", new Value[0]) will call myobj.toString(). Not supported in Player 9 or AIR 1.0. If you call this function and the player to which you are connected doesn't support this feature, this will throw a PlayerDebugException.

Throws:

PlayerDebugException

breakOnCaughtExceptions

void breakOnCaughtExceptions(boolean b)
                             throws NotSupportedException,
                                    NoResponseException

The player always halts on exceptions that are not going to be caught; this call allows the debugger to control its behavior when an exception that *will* be caught is thrown.

Throws:

NotSupportedException - thrown by older players that don't support this feature.

NoResponseException

evalIs

boolean evalIs(Value value,
             Value type)
               throws PlayerDebugException,
                      PlayerFaultException

Evaluate the ActionScript expression "value is type"

Throws:

PlayerDebugException

PlayerFaultException

evalIs

boolean evalIs(Value value,
             String type)
               throws PlayerDebugException,
                      PlayerFaultException

Evaluate the ActionScript expression "value is type"

Throws:

PlayerDebugException

PlayerFaultException

evalInstanceof

boolean evalInstanceof(Value value,
                     Value type)
                       throws PlayerDebugException,
                              PlayerFaultException

Evaluate the ActionScript expression "value instanceof type"

Throws:

PlayerFaultException

PlayerDebugException

evalInstanceof

boolean evalInstanceof(Value value,
                     String type)
                       throws PlayerDebugException,
                              PlayerFaultException

Evaluate the ActionScript expression "value instanceof type"

Throws:

PlayerFaultException

PlayerDebugException

evalIn

boolean evalIn(Value property,
             Value object)
               throws PlayerDebugException,
                      PlayerFaultException

Evaluate the ActionScript expression "property in object"

Throws:

PlayerFaultException

PlayerDebugException

evalAs

Value evalAs(Value value,
           Value type)
             throws PlayerDebugException,
                    PlayerFaultException

Evaluate the ActionScript expression "value as type"

Throws:

PlayerDebugException

PlayerFaultException

supportsWatchpoints

boolean supportsWatchpoints()

Returns whether the target player supports watchpoints.

See Also:

setWatch(Value, String, int)

getDisconnectCause

Exception getDisconnectCause()

Returns the root SocketException that caused the rxMessage() thread to shut down. This works in conjunction with PREF_SOCKET_TIMEOUT and helps in detecting broken connections.

setExceptionBreakpoint

boolean setExceptionBreakpoint(String exceptionClass)
                               throws NoResponseException,
                                      NotConnectedException

Set an exception breakpoint. Returns true if succeeded.

Parameters:

exceptionClass -

Returns:

Throws:

NoResponseException

NotConnectedException

clearExceptionBreakpoint

boolean clearExceptionBreakpoint(String exceptionClass)
                                 throws NoResponseException,
                                        NotConnectedException

Clears an exception breakpoint. Returns true if succeeded.

Parameters:

exceptionClass -

Returns:

Throws:

NoResponseException

NotConnectedException

supportsConcurrency

boolean supportsConcurrency()

Returns whether the target player supports concurrency.

See Also:

#setActiveIsolate(Value)

getWorkers

Isolate[] getWorkers()

Get an array of all workers that the debugger knows of.

refreshWorkers

Isolate[] refreshWorkers()
                         throws NotSupportedException,
                                NotSuspendedException,
                                NoResponseException,
                                NotConnectedException

Ask the player again for a list of all workers. Use this method with caution as it will also reset all state about workers that the debugger is aware of.

Throws:

NotSupportedException

NotSuspendedException

NoResponseException

NotConnectedException

getWorkerSession

IsolateSession getWorkerSession(int isolateId)

Return the worker specific session object that can be used to communicate with that worker.

setLauncher

void setLauncher(ILauncher launcher)

Sets the ILauncher instance which is associated with this session. ILauncher instance is used to terminate the process at the end of the debugging session.

Parameters:

launcher - ILauncher instance used to launch & terminate the process.