/*
* 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;
public interface SessionManager2 extends SessionManager {
/**
* 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.
*
*
* @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 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.
* The callback will be called on a different thread.
* @return 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()
*/
public Process launchForRun(String uri, AIRLaunchInfo airLaunchInfo,
IProgress waitReporter, ILaunchNotification launchNotification) throws IOException;
/**
* 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.
*
* @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 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.
* The callback will be called on a different thread.
* @param launcher
* a launcher instance which will be used to launch.
* @return 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
*/
public Process launchForRun(String uri, AIRLaunchInfo airLaunchInfo,
IProgress waitReporter, ILaunchNotification launchNotification, ILauncher launcher) throws IOException;
/**
* 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.
* <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
* Exception during launch.
*/
public Session launch(String uri, AIRLaunchInfo airLaunchInfo,
boolean forDebugging, IProgress waitReporter, ILaunchNotification launchNotification, ILauncher launcher) throws IOException;
}