flash.tools.debugger.threadsafe

Class ThreadSafeSessionManager

java.lang.Object

flash.tools.debugger.threadsafe.ThreadSafeSessionManager

All Implemented Interfaces:

SessionManager, SessionManager2

public class ThreadSafeSessionManager
extends Object
implements SessionManager2

Thread-safe wrapper for flash.tools.debugger.SessionManager

Author:

Mike Morearty

Field Summary

Fields inherited from interface flash.tools.debugger.SessionManager

PLAYER_SUPPORTS_GET, PREF_ACCEPT_TIMEOUT, PREF_CONNECT_RETRY_ATTEMPTS, PREF_CONNECT_TIMEOUT, PREF_CONNECT_WAIT_INTERVAL, PREF_CONTEXT_RESPONSE_TIMEOUT, PREF_GETVAR_RESPONSE_TIMEOUT, PREF_HIERARCHICAL_VARIABLES, PREF_INVOKE_GETTERS, PREF_RESPONSE_TIMEOUT, PREF_SETVAR_RESPONSE_TIMEOUT, PREF_SOCKET_TIMEOUT, PREF_SUSPEND_WAIT, PREF_SWFSWD_LOAD_TIMEOUT, PREF_URI_MODIFICATION

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
Object	getSyncObject()
static Object	getSyncObject(SessionManager sm)
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.
Session	launch(String uri, AIRLaunchInfo airLaunchInfo, boolean forDebugging, IProgress waitReporter, ILaunchNotification launchNotification, ILauncher launcher) Launches the given string as a URI using the ILauncher Instance.
Process	launchForRun(String uri, AIRLaunchInfo airLaunchInfo, IProgress waitReporter, ILaunchNotification launchNotification) This is, functionally, a clone of the SessionManager.launch() method.
Process	launchForRun(String uri, AIRLaunchInfo airLaunchInfo, IProgress waitReporter, ILaunchNotification launchNotification, ILauncher launcher) This is, functionally, a clone of the SessionManager.launch() method.
Player	playerForUri(String uri, AIRLaunchInfo airLaunchInfo) Returns information about the Flash player which will be used to run the given URI.
void	setDebuggerCallbacks(IDebuggerCallbacks debuggerCallbacks) 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.
static ThreadSafeSessionManager	wrap(SessionManager sessionManager) Wraps a SessionManager inside a ThreadSafeSessionManager.

Methods inherited from class java.lang.Object

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

Method Detail

wrap

public static ThreadSafeSessionManager wrap(SessionManager sessionManager)

Wraps a SessionManager inside a ThreadSafeSessionManager. If the passed-in SessionManager is null, then this function returns null.

getSyncObject

public static Object getSyncObject(SessionManager sm)

accept

public Session accept(IProgress waitReporter)
               throws IOException

Description copied from interface: SessionManager

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.

Specified by:

accept in interface SessionManager

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:

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

getPreference

public int getPreference(String pref)
                  throws NullPointerException

Description copied from interface: SessionManager

Return the value of a particular preference item

Specified by:

getPreference in interface SessionManager

Parameters:

pref - preference name, one of the strings listed above

Throws:

NullPointerException - if pref does not exist

isListening

public boolean isListening()

Description copied from interface: SessionManager

Is this object currently listening for Debug Player connections

Specified by:

isListening in interface SessionManager

Returns:

TRUE currently listening

launch

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

Description copied from interface: SessionManager

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().

Specified by:

launch in interface SessionManager

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:

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

public Player playerForUri(String uri,
                  AIRLaunchInfo airLaunchInfo)

Description copied from interface: SessionManager

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

Specified by:

playerForUri in interface SessionManager

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

public boolean supportsLaunch()

Description copied from interface: SessionManager

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.

Specified by:

supportsLaunch in interface SessionManager

Returns:

true if this platform supports the launch() command.

setPreference

public void setPreference(String pref,
                 int value)

Description copied from interface: SessionManager

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.

Specified by:

setPreference in interface SessionManager

Parameters:

pref - preference name, one of the strings listed above

value - value to set for preference

setPreference

public void setPreference(String pref,
                 String value)

Description copied from interface: SessionManager

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.

Specified by:

setPreference in interface SessionManager

Parameters:

pref - preference name, one of the strings listed above

value - value to set for preference

startListening

public void startListening()
                    throws IOException

Description copied from interface: SessionManager

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

Specified by:

startListening in interface SessionManager

Throws:

IOException - if opening the server side socket fails

stopListening

public void stopListening()
                   throws IOException

Description copied from interface: SessionManager

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.

Specified by:

stopListening in interface SessionManager

Throws:

IOException

setDebuggerCallbacks

public void setDebuggerCallbacks(IDebuggerCallbacks debuggerCallbacks)

Description copied from interface: SessionManager

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.

Specified by:

setDebuggerCallbacks in interface SessionManager

connect

public Session connect(int port,
              IProgress waitReporter)
                throws IOException

Description copied from interface: SessionManager

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.

Specified by:

connect in interface SessionManager

Parameters:

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

Returns:

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

Throws:

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

stopConnecting

public void stopConnecting()
                    throws IOException

Description copied from interface: SessionManager

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.

Specified by:

stopConnecting in interface SessionManager

Throws:

IOException

isConnecting

public boolean isConnecting()

Description copied from interface: SessionManager

Is this object currently connecting to the Debug Player

Specified by:

isConnecting in interface SessionManager

Returns:

TRUE currently connecting

launchForRun

public Process launchForRun(String uri,
                   AIRLaunchInfo airLaunchInfo,
                   IProgress waitReporter,
                   ILaunchNotification launchNotification)
                     throws IOException

Description copied from interface: SessionManager2

This is, functionally, a clone of the SessionManager.launch() method. There are however some differences. -This is to be called only for run launches. only for debug launches, the launch() method creates a Session and binds it to the launch and since the launch() method returns the Session, which will be null in a Run Launch case, we have no way of accessing the Process that was created for the launch. -To enable auto termination of run launches, we need to know the system Process for us to terminate it when necessary. -This method creates the process and binds a process listener to it and then returns the process.

Specified by:

launchForRun in interface SessionManager2

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.

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. The callback will be called on a different thread.

Returns:

a Process to use for the run launch. 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.

Throws:

IOException - see Runtime.exec()

launchForRun

public Process launchForRun(String uri,
                   AIRLaunchInfo airLaunchInfo,
                   IProgress waitReporter,
                   ILaunchNotification launchNotification,
                   ILauncher launcher)
                     throws IOException

Description copied from interface: SessionManager2

This is, functionally, a clone of the SessionManager.launch() method. There are however some differences. -This is to be called only for run launches. only for debug launches, the launch() method creates a Session and binds it to the launch and since the launch() method returns the Session, which will be null in a Run Launch case, we have no way of accessing the Process that was created for the launch. -To enable auto termination of run launches, we need to know the system Process for us to terminate it when necessary. -This method creates the process and binds a process listener to it and then returns the process. - This method used the ILauncher instance passed to launch the application.

Specified by:

launchForRun in interface SessionManager2

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.

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. The callback will be called on a different thread.

launcher - a launcher instance which will be used to launch.

Returns:

a Process to use for the run launch. 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.

Throws:

IOException

launch

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

Description copied from interface: SessionManager2

Launches the given string as a URI using the ILauncher Instance. This API is to provide more flexibility to handle the Player launch in different platforms. 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().

Specified by:

launch in interface SessionManager2

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:

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 - Exception during launch.

getSyncObject

public final Object getSyncObject()