modules/fdbworkers/src/flash/tools/debugger/SessionManager.java - flex-sdk - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package flash.tools.debugger;

 import java.io.IOException;

 /**
  * A SessionManager controls connection establishment and preferences
  * for all debugging sessions with the Flash Player.
  *
  * To begin a new debugging session:
  *
  * <ol>
  * <li> Get a <code>SessionManager</code> from <code>Bootstrap.sessionManager()</code> </li>
  * <li> Call <code>SessionManager.startListening()</code> </li>
  * <li> If you want to have the API launch the Flash Player for you, call
  *      <code>SessionManager.launch()</code>.  If you want to launch the Flash Player
  *      and then have the API connect to it, then launch the Flash Player and then
  *      call <code>SessionManager.accept()</code>. <em>Note:</em> <code>launch()</code>
  *      and <code>accept()</code> are both blocking calls, so you probably don't want
  *      to call them from your main UI thread. </li>
  * <li> Finally, call <code>SessionManager.stopListening()</code>.
  * </ol>
  */
 public interface SessionManager
 {
 	/**
 	 * The preferences are set using the setPreference() method, and
 	 * take effect immediately thereafter.
 	 */

 	/**
 	 * The value used for <code>$accepttimeout</code> controls how long (in
 	 * milliseconds) <code>accept()</code> waits before timing out. The
 	 * default value for this preference is 120000 (2 minutes).
 	 */
 	public static final String PREF_ACCEPT_TIMEOUT				= "$accepttimeout"; //$NON-NLS-1$

 	/**
 	 * Valid values for <code>$urimodification</code> are 0 (off) and 1 (on).
 	 * The default value is 1 (on), which allows this API to modify the URI
 	 * passed to <code>launch()</code> as necessary for creating a debuggable
 	 * version of an MXML file.
 	 */
 	public static final String PREF_URI_MODIFICATION			= "$urimodification"; //$NON-NLS-1$

 	/**
 	 *-----------------------------------------------------------------
 	 * The following are Session specific preferences.  These can be
 	 * modified in this class, resulting in all future sessions using
 	 * the values or they can be modified at the session level via
 	 * Session.setPreference().
 	 *-----------------------------------------------------------------
 	 */

 	/**
 	 * <code>$responsetimeout</code> 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.
 	 */
 	public static final String PREF_RESPONSE_TIMEOUT			= "$responsetimeout"; //$NON-NLS-1$

 	/**
 	 * <code>$sockettimeout</code> 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).
 	 */
 	public static final String PREF_SOCKET_TIMEOUT			= "$sockettimeout"; //$NON-NLS-1$

 	/**
 	 * <code>$contextresponsetimeout</code> 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.
 	 */
 	public static final String PREF_CONTEXT_RESPONSE_TIMEOUT	= "$contextresponsetimeout"; //$NON-NLS-1$

 	/**
 	 * <code>$getvarresponsetimeout</code> 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.
 	 */
 	public static final String PREF_GETVAR_RESPONSE_TIMEOUT		= "$getvarresponsetimeout"; //$NON-NLS-1$

 	/**
 	 * <code>$setvarresponsetimeout</code> 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.
 	 */
 	public static final String PREF_SETVAR_RESPONSE_TIMEOUT		= "$setvarresponsetimeout"; //$NON-NLS-1$

 	/**
 	 * <code>$swfswdloadtimeout<code> 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.
 	 */
 	public static final String PREF_SWFSWD_LOAD_TIMEOUT			= "$swfswdloadtimeout"; //$NON-NLS-1$

 	/**
 	 * <code>$suspendwait</code> is the amount of time (in milliseconds) that
 	 * a Session will wait for the Player to suspend, after a call to
 	 * <code>suspend()</code>.
 	 */
 	public static final String PREF_SUSPEND_WAIT				= "$suspendwait"; //$NON-NLS-1$

 	/**
 	 * <code>$invokegetters</code> is used to determine whether a getter
 	 * property is invoked or not when requested via <code>getVariable()</code>
 	 * The default value is for this to be enabled.
 	 */
 	public static final String PREF_INVOKE_GETTERS				= "$invokegetters"; //$NON-NLS-1$

 	public static final String PLAYER_SUPPORTS_GET				= "$playersupportsget"; //$NON-NLS-1$

 	/**
 	 * <code>$hiervars</code> is used to determine whether the members of
 	 * a variable are shown in a hierchical way.
 	 */
 	public static final String PREF_HIERARCHICAL_VARIABLES		= "$hiervars"; //$NON-NLS-1$

 	/**
 	 * The value used for <code>$connecttimeout</code> controls how long (in
 	 * milliseconds) <code>connect()</code> waits before timing out. The
 	 * default value for this preference is 120000 (2 minutes).
 	 */
 	public static final String PREF_CONNECT_TIMEOUT				= "$connecttimeout"; //$NON-NLS-1$

 	 /**
      * The value used for <code>$connectwaitinterval</code> controls how long (in
      * milliseconds) we wait between subsequent <code>connect()</code> calls. The
      * default value for this preference is 250.
      */
     public static final String PREF_CONNECT_WAIT_INTERVAL = "$connectwaitinterval"; //$NON-NLS-1$

     /**
      * The value used for <code>$connectretryattempts</code> controls how many times
      * the debugger retries connecting to the application. This is time bound by
      * <code>$connecttimeout</code>. 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.
      */
     public static final String PREF_CONNECT_RETRY_ATTEMPTS = "$connectretryattempts"; //$NON-NLS-1$

 	/**
 	 * 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.
 	 * @param pref preference name, one of the strings listed above
 	 * @param value value to set for preference
 	 */
 	public 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.
 	 * @param pref preference name, one of the strings listed above
 	 * @param value value to set for preference
 	 */
 	public void setPreference(String pref, String value);

 	/**
 	 * Return the value of a particular preference item
 	 *
 	 * @param pref preference name, one of the strings listed above
 	 * @throws NullPointerException if pref does not exist
 	 */
 	public int getPreference(String pref) throws NullPointerException;

 	/**
 	 * Listens for Player attempts to open a debug session. This method must be
 	 * called prior to <code>accept()</code> being invoked.
 	 *
 	 * @throws IOException
 	 *             if opening the server side socket fails
 	 */
 	public void startListening() 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 <code>accept</code> to throw SocketExceptions.
 	 */
 	public void stopListening() throws IOException;

 	/**
 	 * Is this object currently listening for Debug Player connections
 	 * @return TRUE currently listening
 	 */
 	public boolean isListening();

 	/**
 	 * 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.
 	 * <p>
 	 * For example "http://localhost:8100/flex/my.mxml" or for a local file on
 	 * Windows, "file://c:/my.swf"
 	 * <p>
 	 * This call will block until a session with the newly launched player is
 	 * created.
 	 * <p>
 	 * It is the caller's responsibility to ensure that no other thread is
 	 * blocking in <code>accept()</code>, since that thread will gain control
 	 * of this session.
 	 * <p>
 	 * Before calling <code>launch()</code>, you should first call
 	 * <code>supportsLaunch()</code>. If <code>supportsLaunch()</code>
 	 * returns false, then you will have to tell the user to manually launch the
 	 * Flash player.
 	 * <p>
 	 * Also, before calling <code>launch()</code>, you must call
 	 * <code>startListening()</code>.
 	 *
 	 * @param 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.
 	 * @param 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
 	 *            <code>null</code>.
 	 * @param forDebugging
 	 *            if <code>true</code>, then the launch is for the purposes
 	 *            of debugging. If <code>false</code>, 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
 	 *            <code>null</code>.
 	 * @param 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 <code>null</code> if the caller doesn't need to
 	 *            know how long it's been waiting.
 	 * @param 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 <code>null</code> 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.
 	 * @return 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 <code>isListening()</code> == false
 	 * @throws FileNotFoundException
 	 *             if file cannot be located
 	 * @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.
 	 * @throws IOException
 	 *             see Runtime.exec()
 	 */
 	public Session launch(String uri, AIRLaunchInfo airLaunchInfo,
 			boolean forDebugging, IProgress waitReporter, ILaunchNotification launchNotification) throws IOException;

 	/**
 	 * Returns information about the Flash player which will be used to run the
 	 * given URI.
 	 *
 	 * @param uri
 	 *            The URI which will be passed to <code>launch()</code> -- for
 	 *            example, <code>http://flexserver/mymovie.mxml</code> or
 	 *            <code>c:\mymovie.swf</code>. If launching an AIR app, this
 	 *            should point to the app's *-app.xml file.
 	 * @param 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.
 	 * @return a {@link Player} which can be used to determine information about
 	 *         the player -- for example, whether it is a debugger-enabled
 	 *         player. Returns <code>null</code> if the player cannot be
 	 *         determined. <em>Important:</em> There are valid situations in
 	 *         which this will return <code>null</code>
 	 */
 	public Player playerForUri(String uri, AIRLaunchInfo airLaunchInfo);

 	/**
 	 * Returns whether this platform supports the <code>launch()</code>
 	 * 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.
 	 *
 	 * @return true if this platform supports the <code>launch()</code>
 	 *         command.
 	 */
 	public boolean supportsLaunch();

 	/**
 	 * Blocks until the next available player debug session commences, or until
 	 * <code>getPreference(PREF_ACCEPT_TIMEOUT)</code> milliseconds pass.
 	 * <p>
 	 * Before calling <code>launch()</code>, you must call
 	 * <code>startListening()</code>.
 	 * <p>
 	 * Once a Session is obtained, Session.bind() must be called prior to any
 	 * other Session method.
 	 *
 	 * @param 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 <code>null</code> if the caller doesn't need to know how
 	 *            long it's been waiting.
 	 * @throws BindException
 	 *             if isListening() == false
 	 * @throws IOException -
 	 *             see java.net.ServerSocket.accept()
 	 */
 	public Session accept(IProgress waitReporter) throws IOException;

 	/**
 	 * 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 <code>DefaultDebuggerCallbacks</code> object.
 	 */
 	public void setDebuggerCallbacks(IDebuggerCallbacks debugger);

 	/**
 	 * Initiate a debug session by connecting to the specified port. Blocks
 	 * until a connection is made, or until
 	 * <code>getPreference(PREF_CONNECT_TIMEOUT)</code> milliseconds pass.
 	 * <p>
 	 * This work-flow is a reverse of <code>accept()</code> 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.
 	 * <p>
 	 * Use <code>stopConnecting()</code> to cancel connect,
 	 * <code>isConnecting()</code> to check if we are currently trying to
 	 * connect.
 	 *
 	 * @param port - The port to connect to. See DProtocol.DEBUG_CONNECT_PORT.
 	 * @param waitReporter
 	 * @return A Session object on which bind() has already been called.
 	 * @throws IOException - This may have a wrapped VersionException due to bind()
 	 */
 	public Session connect(int port, IProgress waitReporter) 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 <code>connect</code> to throw SocketExceptions.
 	 */
 	public void stopConnecting() throws IOException;

 	/**
 	 * Is this object currently connecting to the Debug Player
 	 * @return TRUE currently connecting
 	 */
 	public boolean isConnecting();
 }
	/*
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package flash.tools.debugger;

	import java.io.IOException;

	/**
	* A SessionManager controls connection establishment and preferences
	* for all debugging sessions with the Flash Player.
	*
	* To begin a new debugging session:
	*
	* <ol>
	* <li> Get a <code>SessionManager</code> from <code>Bootstrap.sessionManager()</code> </li>
	* <li> Call <code>SessionManager.startListening()</code> </li>
	* <li> If you want to have the API launch the Flash Player for you, call
	* <code>SessionManager.launch()</code>. If you want to launch the Flash Player
	* and then have the API connect to it, then launch the Flash Player and then
	* call <code>SessionManager.accept()</code>. <em>Note:</em> <code>launch()</code>
	* and <code>accept()</code> are both blocking calls, so you probably don't want
	* to call them from your main UI thread. </li>
	* <li> Finally, call <code>SessionManager.stopListening()</code>.
	* </ol>
	*/
	public interface SessionManager
	{
	/**
	* The preferences are set using the setPreference() method, and
	* take effect immediately thereafter.
	*/

	/**
	* The value used for <code>$accepttimeout</code> controls how long (in
	* milliseconds) <code>accept()</code> waits before timing out. The
	* default value for this preference is 120000 (2 minutes).
	*/
	public static final String PREF_ACCEPT_TIMEOUT = "$accepttimeout"; //$NON-NLS-1$

	/**
	* Valid values for <code>$urimodification</code> are 0 (off) and 1 (on).
	* The default value is 1 (on), which allows this API to modify the URI
	* passed to <code>launch()</code> as necessary for creating a debuggable
	* version of an MXML file.
	*/
	public static final String PREF_URI_MODIFICATION = "$urimodification"; //$NON-NLS-1$

	/**
	*-----------------------------------------------------------------
	* The following are Session specific preferences. These can be
	* modified in this class, resulting in all future sessions using
	* the values or they can be modified at the session level via
	* Session.setPreference().
	*-----------------------------------------------------------------
	*/

	/**
	* <code>$responsetimeout</code> 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.
	*/
	public static final String PREF_RESPONSE_TIMEOUT = "$responsetimeout"; //$NON-NLS-1$

	/**
	* <code>$sockettimeout</code> 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).
	*/
	public static final String PREF_SOCKET_TIMEOUT = "$sockettimeout"; //$NON-NLS-1$

	/**
	* <code>$contextresponsetimeout</code> 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.
	*/
	public static final String PREF_CONTEXT_RESPONSE_TIMEOUT = "$contextresponsetimeout"; //$NON-NLS-1$

	/**
	* <code>$getvarresponsetimeout</code> 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.
	*/
	public static final String PREF_GETVAR_RESPONSE_TIMEOUT = "$getvarresponsetimeout"; //$NON-NLS-1$

	/**
	* <code>$setvarresponsetimeout</code> 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.
	*/
	public static final String PREF_SETVAR_RESPONSE_TIMEOUT = "$setvarresponsetimeout"; //$NON-NLS-1$

	/**
	* <code>$swfswdloadtimeout<code> 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.
	*/
	public static final String PREF_SWFSWD_LOAD_TIMEOUT = "$swfswdloadtimeout"; //$NON-NLS-1$

	/**
	* <code>$suspendwait</code> is the amount of time (in milliseconds) that
	* a Session will wait for the Player to suspend, after a call to
	* <code>suspend()</code>.
	*/
	public static final String PREF_SUSPEND_WAIT = "$suspendwait"; //$NON-NLS-1$

	/**
	* <code>$invokegetters</code> is used to determine whether a getter
	* property is invoked or not when requested via <code>getVariable()</code>
	* The default value is for this to be enabled.
	*/
	public static final String PREF_INVOKE_GETTERS = "$invokegetters"; //$NON-NLS-1$

	public static final String PLAYER_SUPPORTS_GET = "$playersupportsget"; //$NON-NLS-1$

	/**
	* <code>$hiervars</code> is used to determine whether the members of
	* a variable are shown in a hierchical way.
	*/
	public static final String PREF_HIERARCHICAL_VARIABLES = "$hiervars"; //$NON-NLS-1$

	/**
	* The value used for <code>$connecttimeout</code> controls how long (in
	* milliseconds) <code>connect()</code> waits before timing out. The
	* default value for this preference is 120000 (2 minutes).
	*/
	public static final String PREF_CONNECT_TIMEOUT = "$connecttimeout"; //$NON-NLS-1$

	/**
	* The value used for <code>$connectwaitinterval</code> controls how long (in
	* milliseconds) we wait between subsequent <code>connect()</code> calls. The
	* default value for this preference is 250.
	*/
	public static final String PREF_CONNECT_WAIT_INTERVAL = "$connectwaitinterval"; //$NON-NLS-1$

	/**
	* The value used for <code>$connectretryattempts</code> controls how many times
	* the debugger retries connecting to the application. This is time bound by
	* <code>$connecttimeout</code>. 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.
	*/
	public static final String PREF_CONNECT_RETRY_ATTEMPTS = "$connectretryattempts"; //$NON-NLS-1$

	/**
	* 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.
	* @param pref preference name, one of the strings listed above
	* @param value value to set for preference
	*/
	public 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.
	* @param pref preference name, one of the strings listed above
	* @param value value to set for preference
	*/
	public void setPreference(String pref, String value);

	/**
	* Return the value of a particular preference item
	*
	* @param pref preference name, one of the strings listed above
	* @throws NullPointerException if pref does not exist
	*/
	public int getPreference(String pref) throws NullPointerException;

	/**
	* Listens for Player attempts to open a debug session. This method must be
	* called prior to <code>accept()</code> being invoked.
	*
	* @throws IOException
	* if opening the server side socket fails
	*/
	public void startListening() 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 <code>accept</code> to throw SocketExceptions.
	*/
	public void stopListening() throws IOException;

	/**
	* Is this object currently listening for Debug Player connections
	* @return TRUE currently listening
	*/
	public boolean isListening();

	/**
	* 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.
	* <p>
	* For example "http://localhost:8100/flex/my.mxml" or for a local file on
	* Windows, "file://c:/my.swf"
	* <p>
	* This call will block until a session with the newly launched player is
	* created.
	* <p>
	* It is the caller's responsibility to ensure that no other thread is
	* blocking in <code>accept()</code>, since that thread will gain control
	* of this session.
	* <p>
	* Before calling <code>launch()</code>, you should first call
	* <code>supportsLaunch()</code>. If <code>supportsLaunch()</code>
	* returns false, then you will have to tell the user to manually launch the
	* Flash player.
	* <p>
	* Also, before calling <code>launch()</code>, you must call
	* <code>startListening()</code>.
	*
	* @param 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.
	* @param 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
	* <code>null</code>.
	* @param forDebugging
	* if <code>true</code>, then the launch is for the purposes
	* of debugging. If <code>false</code>, 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
	* <code>null</code>.
	* @param 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 <code>null</code> if the caller doesn't need to
	* know how long it's been waiting.
	* @param 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 <code>null</code> 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.
	* @return 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 <code>isListening()</code> == false
	* @throws FileNotFoundException
	* if file cannot be located
	* @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.
	* @throws IOException
	* see Runtime.exec()
	*/
	public Session launch(String uri, AIRLaunchInfo airLaunchInfo,
	boolean forDebugging, IProgress waitReporter, ILaunchNotification launchNotification) throws IOException;

	/**
	* Returns information about the Flash player which will be used to run the
	* given URI.
	*
	* @param uri
	* The URI which will be passed to <code>launch()</code> -- for
	* example, <code>http://flexserver/mymovie.mxml</code> or
	* <code>c:\mymovie.swf</code>. If launching an AIR app, this
	* should point to the app's *-app.xml file.
	* @param 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.
	* @return a {@link Player} which can be used to determine information about
	* the player -- for example, whether it is a debugger-enabled
	* player. Returns <code>null</code> if the player cannot be
	* determined. <em>Important:</em> There are valid situations in
	* which this will return <code>null</code>
	*/
	public Player playerForUri(String uri, AIRLaunchInfo airLaunchInfo);

	/**
	* Returns whether this platform supports the <code>launch()</code>
	* 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.
	*
	* @return true if this platform supports the <code>launch()</code>
	* command.
	*/
	public boolean supportsLaunch();

	/**
	* Blocks until the next available player debug session commences, or until
	* <code>getPreference(PREF_ACCEPT_TIMEOUT)</code> milliseconds pass.
	* <p>
	* Before calling <code>launch()</code>, you must call
	* <code>startListening()</code>.
	* <p>
	* Once a Session is obtained, Session.bind() must be called prior to any
	* other Session method.
	*
	* @param 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 <code>null</code> if the caller doesn't need to know how
	* long it's been waiting.
	* @throws BindException
	* if isListening() == false
	* @throws IOException -
	* see java.net.ServerSocket.accept()
	*/
	public Session accept(IProgress waitReporter) throws IOException;

	/**
	* 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 <code>DefaultDebuggerCallbacks</code> object.
	*/
	public void setDebuggerCallbacks(IDebuggerCallbacks debugger);

	/**
	* Initiate a debug session by connecting to the specified port. Blocks
	* until a connection is made, or until
	* <code>getPreference(PREF_CONNECT_TIMEOUT)</code> milliseconds pass.
	* <p>
	* This work-flow is a reverse of <code>accept()</code> 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.
	* <p>
	* Use <code>stopConnecting()</code> to cancel connect,
	* <code>isConnecting()</code> to check if we are currently trying to
	* connect.
	*
	* @param port - The port to connect to. See DProtocol.DEBUG_CONNECT_PORT.
	* @param waitReporter
	* @return A Session object on which bind() has already been called.
	* @throws IOException - This may have a wrapped VersionException due to bind()
	*/
	public Session connect(int port, IProgress waitReporter) 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 <code>connect</code> to throw SocketExceptions.
	*/
	public void stopConnecting() throws IOException;

	/**
	* Is this object currently connecting to the Debug Player
	* @return TRUE currently connecting
	*/
	public boolean isConnecting();
	}