flash.tools.debugger

Interface SessionManager

All Known Subinterfaces:

SessionManager2

All Known Implementing Classes:

PlayerSessionManager, ThreadSafeSessionManager

public interface SessionManager

A SessionManager controls connection establishment and preferences for all debugging sessions with the Flash Player. To begin a new debugging session:

1. Get a SessionManager from Bootstrap.sessionManager()
2. Call SessionManager.startListening()
3. If you want to have the API launch the Flash Player for you, call SessionManager.launch(). If you want to launch the Flash Player and then have the API connect to it, then launch the Flash Player and then call SessionManager.accept(). Note: launch() and accept() are both blocking calls, so you probably don't want to call them from your main UI thread.
4. Finally, call SessionManager.stopListening().

Field Summary

Fields

Modifier and Type	Field and Description
static String	PLAYER_SUPPORTS_GET
static String	PREF_ACCEPT_TIMEOUT The value used for $accepttimeout controls how long (in milliseconds) accept() waits before timing out.
static String	PREF_CONNECT_RETRY_ATTEMPTS The value used for $connectretryattempts controls how many times the debugger retries connecting to the application.
static String	PREF_CONNECT_TIMEOUT The value used for $connecttimeout controls how long (in milliseconds) connect() waits before timing out.
static String	PREF_CONNECT_WAIT_INTERVAL The value used for $connectwaitinterval controls how long (in milliseconds) we wait between subsequent connect() calls.
static String	PREF_CONTEXT_RESPONSE_TIMEOUT $contextresponsetimeout is used to determine how long (in milliseconds) the session will wait for a player response from a request to get context, before giving up on the request and throwing an Exception.
static String	PREF_GETVAR_RESPONSE_TIMEOUT $getvarresponsetimeout is used to determine how long (in milliseconds) the session will wait, for a player response to a get variable request before giving up on the request and throwing an Exception.
static String	PREF_HIERARCHICAL_VARIABLES $hiervars is used to determine whether the members of a variable are shown in a hierchical way.
static String	PREF_INVOKE_GETTERS $invokegetters is used to determine whether a getter property is invoked or not when requested via getVariable() The default value is for this to be enabled.
static String	PREF_RESPONSE_TIMEOUT $responsetimeout is used to determine how long (in milliseconds) the session will wait, for a player response before giving up on the request and throwing an Exception.
static String	PREF_SETVAR_RESPONSE_TIMEOUT $setvarresponsetimeout is the amount of time (in milliseconds) that a setter in the user's code will be given to execute, before the player interrupts it with a ScriptTimeoutError.
static String	PREF_SOCKET_TIMEOUT $sockettimeout is used to determine how long (in milliseconds) the session will wait on a Socket recv call.
static String	PREF_SUSPEND_WAIT $suspendwait is the amount of time (in milliseconds) that a Session will wait for the Player to suspend, after a call to suspend().
static String	PREF_SWFSWD_LOAD_TIMEOUT $swfswdloadtimeout is used to determine how long (in milliseconds) the session will wait, for a player response to a swf/swd load request before giving up on the request and throwing an Exception.
static String	PREF_URI_MODIFICATION Valid values for $urimodification are 0 (off) and 1 (on).

Method Summary

Methods

Modifier and Type	Method and Description
Session	accept(IProgress waitReporter) Blocks until the next available player debug session commences, or until getPreference(PREF_ACCEPT_TIMEOUT) milliseconds pass.
Session	connect(int port, IProgress waitReporter) Initiate a debug session by connecting to the specified port.
int	getPreference(String pref) Return the value of a particular preference item
boolean	isConnecting() Is this object currently connecting to the Debug Player
boolean	isListening() Is this object currently listening for Debug Player connections
Session	launch(String uri, AIRLaunchInfo airLaunchInfo, boolean forDebugging, IProgress waitReporter, ILaunchNotification launchNotification) Launches a Player using the given string as a URI, as defined by RFC2396.
Player	playerForUri(String uri, AIRLaunchInfo airLaunchInfo) Returns information about the Flash player which will be used to run the given URI.
void	setDebuggerCallbacks(IDebuggerCallbacks debugger) Tells the session manager to use the specified IDebuggerCallbacks for performing certain operatios, such as finding the Flash Player and launching the debug target.
void	setPreference(String pref, int value) Set preference for this manager and for subsequent Sessions that are initiated after this call.
void	setPreference(String pref, String value) Set preference for this manager and for subsequent Sessions that are initiated after this call.
void	startListening() Listens for Player attempts to open a debug session.
void	stopConnecting() Stops connecting to the Player for a debug session.
void	stopListening() Stops listening for new Player attempts to open a debug session.
boolean	supportsLaunch() Returns whether this platform supports the launch() command; that is, whether the debugger can programmatically launch the Flash player.

Field Detail

PREF_ACCEPT_TIMEOUT

static final String PREF_ACCEPT_TIMEOUT

The value used for $accepttimeout controls how long (in milliseconds) accept() waits before timing out. The default value for this preference is 120000 (2 minutes).

See Also:

Constant Field Values

PREF_URI_MODIFICATION

static final String PREF_URI_MODIFICATION

Valid values for $urimodification are 0 (off) and 1 (on). The default value is 1 (on), which allows this API to modify the URI passed to launch() as necessary for creating a debuggable version of an MXML file.

See Also:

Constant Field Values

PREF_RESPONSE_TIMEOUT

static final String PREF_RESPONSE_TIMEOUT

$responsetimeout is used to determine how long (in milliseconds) the session will wait, for a player response before giving up on the request and throwing an Exception.

See Also:

Constant Field Values

PREF_SOCKET_TIMEOUT

static final String PREF_SOCKET_TIMEOUT

$sockettimeout is used to determine how long (in milliseconds) the session will wait on a Socket recv call. On timeout, we do not immediately abort the session, instead we write a squelch message to player. If the write succeeds, we assume everything is normal.This helps identify broken connections that are relevant when performing WiFi debugging. This is -1 by default to indicate no timeout (for backward compatibility).

See Also:

Constant Field Values

PREF_CONTEXT_RESPONSE_TIMEOUT

static final String PREF_CONTEXT_RESPONSE_TIMEOUT

$contextresponsetimeout is used to determine how long (in milliseconds) the session will wait for a player response from a request to get context, before giving up on the request and throwing an Exception.

See Also:

Constant Field Values

PREF_GETVAR_RESPONSE_TIMEOUT

static final String PREF_GETVAR_RESPONSE_TIMEOUT

$getvarresponsetimeout is used to determine how long (in milliseconds) the session will wait, for a player response to a get variable request before giving up on the request and throwing an Exception.

See Also:

Constant Field Values

PREF_SETVAR_RESPONSE_TIMEOUT

static final String PREF_SETVAR_RESPONSE_TIMEOUT

$setvarresponsetimeout is the amount of time (in milliseconds) that a setter in the user's code will be given to execute, before the player interrupts it with a ScriptTimeoutError. Default value is 5000 ms.

See Also:

Constant Field Values

PREF_SWFSWD_LOAD_TIMEOUT

static final String PREF_SWFSWD_LOAD_TIMEOUT

$swfswdloadtimeout is used to determine how long (in milliseconds) the session will wait, for a player response to a swf/swd load request before giving up on the request and throwing an Exception.

See Also:

Constant Field Values

PREF_SUSPEND_WAIT

static final String PREF_SUSPEND_WAIT

$suspendwait is the amount of time (in milliseconds) that a Session will wait for the Player to suspend, after a call to suspend().

See Also:

Constant Field Values

PREF_INVOKE_GETTERS

static final String PREF_INVOKE_GETTERS

$invokegetters is used to determine whether a getter property is invoked or not when requested via getVariable() The default value is for this to be enabled.

See Also:

Constant Field Values

PLAYER_SUPPORTS_GET

static final String PLAYER_SUPPORTS_GET

See Also:

Constant Field Values

PREF_HIERARCHICAL_VARIABLES

static final String PREF_HIERARCHICAL_VARIABLES

$hiervars is used to determine whether the members of a variable are shown in a hierchical way.

See Also:

Constant Field Values

PREF_CONNECT_TIMEOUT

static final String PREF_CONNECT_TIMEOUT

The value used for $connecttimeout controls how long (in milliseconds) connect() waits before timing out. The default value for this preference is 120000 (2 minutes).

See Also:

Constant Field Values

PREF_CONNECT_WAIT_INTERVAL

static final String PREF_CONNECT_WAIT_INTERVAL

The value used for $connectwaitinterval controls how long (in milliseconds) we wait between subsequent connect() calls. The default value for this preference is 250.

See Also:

Constant Field Values

PREF_CONNECT_RETRY_ATTEMPTS

static final String PREF_CONNECT_RETRY_ATTEMPTS

The value used for $connectretryattempts controls how many times the debugger retries connecting to the application. This is time bound by $connecttimeout. The default value for this preference is -1 and indicates that the debugger should retry till the timeout period has elapsed. Setting this to zero will disable the retry mechanism.

See Also:

Constant Field Values

Method Detail

setPreference

void setPreference(String pref,
                 int value)

Set preference for this manager and for subsequent Sessions that are initiated after this call. 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

setPreference

void setPreference(String pref,
                 String value)

Set preference for this manager and for subsequent Sessions that are initiated after this call. 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 above

Throws:

NullPointerException - if pref does not exist

startListening

void startListening()
                    throws IOException

Listens for Player attempts to open a debug session. This method must be called prior to accept() being invoked.

Throws:

IOException - if opening the server side socket fails

stopListening

void stopListening()
                   throws IOException

Stops listening for new Player attempts to open a debug session. The method DOES NOT terminate currently connected sessions, but will cause threads blocked in accept to throw SocketExceptions.

Throws:

IOException

isListening

boolean isListening()

Is this object currently listening for Debug Player connections

Returns:

TRUE currently listening

launch

Session launch(String uri,
             AIRLaunchInfo airLaunchInfo,
             boolean forDebugging,
             IProgress waitReporter,
             ILaunchNotification launchNotification)
               throws IOException

Launches a Player using the given string as a URI, as defined by RFC2396. It is expected that the operating system will be able to launch the appropriate player application given this URI.

For example "http://localhost:8100/flex/my.mxml" or for a local file on Windows, "file://c:/my.swf"

This call will block until a session with the newly launched player is created.

It is the caller's responsibility to ensure that no other thread is blocking in accept(), since that thread will gain control of this session.

Before calling launch(), you should first call supportsLaunch(). If supportsLaunch() returns false, then you will have to tell the user to manually launch the Flash player.

Also, before calling launch(), you must call startListening().

Parameters:

uri - which will launch a Flash player under running OS. For Flash/Flex apps, this can point to either a SWF or an HTML file. For AIR apps, this must point to the application.xml file for the application.

airLaunchInfo - If trying to launch an AIR application, this argument must be specified; it gives more information about how to do the launch. If trying to launch a regular web-based Flash or Flex application, such as one that will be in a browser or in the standalone Flash Player, this argument should be null.

forDebugging - if true, then the launch is for the purposes of debugging. If false, then the launch is simply because the user wants to run the movie but not debug it; in that case, the return value of this function will be null.

waitReporter - a progress monitor to allow accept() to notify its parent how long it has been waiting for the Flash player to connect to it. May be null if the caller doesn't need to know how long it's been waiting.

launchNotification - a notifier to notify the caller about ADL Exit Code. Main usage is for ADL Exit Code 1 (Successful invocation of an already running AIR application. ADL exits immediately). May be null if no need to listen ADL. Will only be called if forDebugging is false. (If forDebugging is true, error conditions are handled by throwing an exception.) The callback will be called on a different thread.

Returns:

a Session to use for debugging, or null if forDebugging==false. The return value is not used to indicate an error -- exceptions are used for that. If this function returns without throwing an exception, then the return value will always be non-null if forDebugging==true, or null if forDebugging==false.

Throws:

BindException - if isListening() == false

FileNotFoundException - if file cannot be located

CommandLineException - if the program that was launched exited unexpectedly. This will be returned, for example, when launching an AIR application, if adl exits with an error code. CommandLineException includes functions to return any error text that may have been sent to stdout/stderr, and the exit code of the program.

IOException - see Runtime.exec()

playerForUri

Player playerForUri(String uri,
                  AIRLaunchInfo airLaunchInfo)

Returns information about the Flash player which will be used to run the given URI.

Parameters:

uri - The URI which will be passed to launch() -- for example, http://flexserver/mymovie.mxml or c:\mymovie.swf. If launching an AIR app, this should point to the app's *-app.xml file.

airLaunchInfo - If launching an AIR app, this should, if possible, contain info about the version of AIR being launched, but it can be null if you don't have that information. If launching a web-based app, this should be null.

Returns:

a Player which can be used to determine information about the player -- for example, whether it is a debugger-enabled player. Returns null if the player cannot be determined. Important: There are valid situations in which this will return null

supportsLaunch

boolean supportsLaunch()

Returns whether this platform supports the launch() command; that is, whether the debugger can programmatically launch the Flash player. If this function returns false, then the debugger will have to tell the user to manually launch the Flash player.

Returns:

true if this platform supports the launch() command.

accept

Session accept(IProgress waitReporter)
               throws IOException

Blocks until the next available player debug session commences, or until getPreference(PREF_ACCEPT_TIMEOUT) milliseconds pass.

Before calling launch(), you must call startListening().

Once a Session is obtained, Session.bind() must be called prior to any other Session method.

Parameters:

waitReporter - a progress monitor to allow accept() to notify its parent how long it has been waiting for the Flash player to connect to it. May be null if the caller doesn't need to know how long it's been waiting.

Throws:

BindException - if isListening() == false

IOException - - see java.net.ServerSocket.accept()

setDebuggerCallbacks

void setDebuggerCallbacks(IDebuggerCallbacks debugger)

Tells the session manager to use the specified IDebuggerCallbacks for performing certain operatios, such as finding the Flash Player and launching the debug target. If you do not call this, the session manager will use a DefaultDebuggerCallbacks object.

connect

Session connect(int port,
              IProgress waitReporter)
                throws IOException

Initiate a debug session by connecting to the specified port. Blocks until a connection is made, or until getPreference(PREF_CONNECT_TIMEOUT) milliseconds pass.

This work-flow is a reverse of accept() and suited for cases where the player is unable to initiate the connection. The player must be listening on the specified port for an incoming debug connection. In addition, this function calls bind() on the session to determine if the handshake was successful so that retry works correctly even across port-forwards.

Use stopConnecting() to cancel connect, isConnecting() to check if we are currently trying to connect.

Parameters:

port - - The port to connect to. See DProtocol.DEBUG_CONNECT_PORT.

waitReporter -

Returns:

A Session object on which bind() has already been called.

Throws:

IOException - - This may have a wrapped VersionException due to bind()

stopConnecting

void stopConnecting()
                    throws IOException

Stops connecting to the Player for a debug session. The method DOES NOT terminate currently connected sessions, but will cause threads blocked in connect to throw SocketExceptions.

Throws:

IOException

isConnecting

boolean isConnecting()

Is this object currently connecting to the Debug Player

Returns:

TRUE currently connecting