/*
* 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 flash.tools.debugger.events.DebugEvent;
import flash.tools.debugger.expression.PlayerFaultException;
/**
* 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.
*/
public interface Session
{
/**
* Returns the URL that identifies this Session.
* Note: this may not be unique across Sessions if
* the same launching mechanism and SWF are used.
* @return URI received from the connected Player.
* It identifies the debugging session
*/
public String getURI();
/**
* Returns the Process object, if any, that triggered this Session.
* @return the Process object that was used to create this Session.
* If SessionManager.launch() was not used, then null is returned.
*/
public Process getLaunchProcess();
/**
* 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.
* @param pref preference name, one of the strings listed above
* @param value value to set for preference
*/
public void setPreference(String pref, int value);
/**
* Return the value of a particular preference item
*
* @param pref preference name, one of the strings listed in <code>SessionManager</code>
* @throws NullPointerException if pref does not exist
* @see SessionManager
*/
public int getPreference(String pref) throws NullPointerException;
/**
* Is the Player currently connected for this session. This function
* must be thread-safe.
*
* @return true if connection is alive
*/
public boolean isConnected();
/**
* Allow the session to start communicating with the player. This
* call must be made PRIOR to any other Session method call.
* @return true if bind was successful.
* @throws VersionException connected to Player which does not support all API completely
*/
public boolean bind() throws VersionException;
/**
* Permanently stops the debugging session and breaks the
* connection. If this Session is used for any subsequent
* calls exceptions will be thrown.
* <p>
* 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.
* <p>
* 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.
*/
public void unbind();
/**
* Permanently stops the debugging session and breaks the connection. If
* this session ID is used for any subsequent calls exceptions will be
* thrown.
* <p>
* 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:
*
* <ul>
* <li> 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. </li>
* <li> 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. </li>
* </ul>
*
* <p>
* If SessionManager.launch() was used to initiate the Session then calling
* this function also causes getLaunchProcess().destroy() to be called.
* <p>
* Note: this method first calls unbind() if needed.
*/
public void terminate();
/**
* Continue a halted session. Execution of the ActionScript
* will commence until a reason for halting exists. That
* is, a breakpoint is reached or the <code>suspend()</code> method is called.
* <p>
* 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
* @throws NotSuspendedException if Player is already running
* @throws NotConnectedException if Player is disconnected from Session
*/
public void resume() throws NotSuspendedException, NotConnectedException, NoResponseException;
/**
* Halt a running session. Execution of the ActionScript
* will stop at the next possible breakpoint.
* <p>
* 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
* @throws SuspendedException if Player is already suspended
* @throws NotConnectedException if Player is disconnected from Session
*/
public void suspend() throws SuspendedException, NotConnectedException, NoResponseException;
/**
* Is the Player currently halted awaiting requests, such as continue,
* stepOut, stepIn, stepOver. This function is guaranteed to be thread-safe.
*
* @return true if player halted
* @throws NotConnectedException
* if Player is disconnected from Session
*/
public boolean isSuspended() throws NotConnectedException;
/**
* Returns a SuspendReason integer which indicates
* why the Player has suspended execution.
* @return see SuspendReason
* @throws NotConnectedException if Player is disconnected from Session
*/
public int suspendReason() 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.
* @return array of call frames with 0th element representing the current frame.
* @throws NotConnectedException if Player is disconnected from Session
*/
public Frame[] getFrames() throws NotConnectedException;
/**
* Step to the next executable source line within the
* program, will enter into functions.
* <p>
* 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
* @throws NotSuspendedException if Player is running
* @throws NotConnectedException if Player is disconnected from Session
*/
public void stepInto() throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Step out of the current method/function onto the
* next executable soruce line.
* <p>
* 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
* @throws NotSuspendedException if Player is running
* @throws NotConnectedException if Player is disconnected from Session
*/
public void stepOut() throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Step to the next executable source line within
* the program, will NOT enter into functions.
* <p>
* 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
* @throws NotSuspendedException if Player is running
* @throws NotConnectedException if Player is disconnected from Session
*/
public void stepOver() 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
* @throws NotSuspendedException if Player is running
* @throws NotConnectedException if Player is disconnected from Session
*/
public void stepContinue() throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* 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.
*
* @return array of records describing the SWFs
* @throws NoResponseException if times out
*/
public SwfInfo[] getSwfs() throws NoResponseException;
/**
* Get a list of the current breakpoints. No specific ordering
* of the breakpoints is implied by the array.
* @return breakpoints currently set.
* @throws NoResponseException if times out
* @throws NotConnectedException if Player is disconnected from Session
*/
public Location[] getBreakpointList() throws NoResponseException, NotConnectedException;
/**
* Set a breakpoint on a line within the given file.
* <p>
* <em>Warning:</em> <code>setBreakpoint()</code> and
* <code>clearBreakpoint()</code> do not keep track of how many times they
* have been called for a given Location. For example, if you make two calls
* to <code>setBreakpoint()</code> for file X.as line 10, and then one
* call to <code>clearBreakpoint()</code> 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.
*
* @return null if breakpoint not set, otherwise
* Location of breakpoint.
* @throws NoResponseException if times out
* @throws NotConnectedException if Player is disconnected from Session
*/
public Location setBreakpoint(int fileId, int lineNum) 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().
* <p>
* <em>Warning:</em> <code>setBreakpoint()</code> and
* <code>clearBreakpoint()</code> do not keep track of how many times they
* have been called for a given Location. For example, if you make two calls
* to <code>setBreakpoint()</code> for file X.as line 10, and then one
* call to <code>clearBreakpoint()</code> 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.
*
* @return null if breakpoint was not removed.
* @throws NoResponseException
* if times out
* @throws NotConnectedException
* if Player is disconnected from Session
*/
public Location clearBreakpoint(Location location) 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.
* @return watchpoints currently set.
* @throws NoResponseException if times out
* @throws NotConnectedException if Player is disconnected from Session
* @since Version 2
*/
public Watch[] getWatchList() throws NoResponseException, NotConnectedException;
/**
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
*
* @param v the variable, upon whose member, the watch is to be placed.
* @param 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.
* @param kind access type that will trigger the watchpoint to fire --
* read, write, or read/write. See <code>WatchKind</code>.
* @return null if watchpoint was not created.
* @throws NoResponseException if times out
* @throws NotConnectedException if Player is disconnected from Session
* @throws 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 WatchKind
*/
public Watch setWatch(Value v, String memberName, int kind) throws NoResponseException, NotConnectedException, NotSupportedException;
/**
* Enables or disables a watchpoint.
*
* @param watch
* the watch to enable or disable
* @param enabled
* whether to enable it or disable it
* @throws NotSupportedException
* @throws NotConnectedException
* @throws NoResponseException
*/
public Watch setWatch(Watch watch) throws NoResponseException, NotConnectedException, NotSupportedException;
/**
* Remove a previously created watchpoint. The watchpoint
* that was removed will be returned upon a sucessful call.
* @return null if watchpoint was not removed.
* @throws NoResponseException if times out
* @throws NotConnectedException if Player is disconnected from Session
* @since Version 2
*/
public Watch clearWatch(Watch watch) throws NoResponseException, NotConnectedException;
/**
* Obtains a list of variables that are local to the current
* halted state.
* @deprecated As of version 2.
* @see Frame#getLocals
*/
public Variable[] getVariableList() throws NotSuspendedException, NoResponseException, NotConnectedException, VersionException;
/**
* 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'.
* @param valueId identifier from Value class or
* from a call to Value.getId()
* @return null, if value cannot be found or
* value with the specific id.
* @throws NoResponseException if times out
* @throws NotSuspendedException if Player is running
* @throws NotConnectedException if Player is disconnected from Session
*/
public Value getValue(long valueId) throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Looks up a global name, like "MyClass", "String", etc.
*
* @return its value, or <code>null</code> if the global does not exist.
*/
public Value getGlobal(String name) throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Events provide a mechanism whereby status information is provided from
* the Player in a timely fashion.
* <p>
* The caller has the option of either polling the event queue via
* <code>nextEvent()</code> or calling <code>waitForEvent()</code> which
* blocks the calling thread until one or more events exist in the queue.
*
* @throws NotConnectedException
* if Session is disconnected from Player
* @throws InterruptedException
*/
public void waitForEvent() throws NotConnectedException, InterruptedException;
/**
* Returns the number of events currently in the queue. This function
* is guaranteed to be thread-safe.
*/
public int getEventCount();
/**
* Removes and returns the next event from queue
*/
public DebugEvent nextEvent();
/**
* Gets the SourceLocator for this session. If none has been
* specified, returns null.
*/
public SourceLocator getSourceLocator();
/**
* Sets the SourceLocator for this session. This can be used in order
* to override the default rules used for finding source files.
*/
public void setSourceLocator(SourceLocator sourceLocator);
/**
* 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.
*/
public Value callConstructor(String classname, Value[] args) throws PlayerDebugException;
/**
* Invokes a function. For example, calling
* <code>callFunction(myobj, "toString", new Value[0])</code> will call
* <code>myobj.toString()</code>. 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.
*/
public Value callFunction(Value thisObject, String functionName, Value[] args) throws PlayerDebugException;
/**
* 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.
* @throws NoResponseException
*/
public void breakOnCaughtExceptions(boolean b) throws NotSupportedException, NoResponseException;
/**
* Evaluate the ActionScript expression "value is type"
*
* @throws PlayerDebugException
* @throws PlayerFaultException
*/
public boolean evalIs(Value value, Value type) throws PlayerDebugException, PlayerFaultException;
/**
* Evaluate the ActionScript expression "value is type"
*
* @throws PlayerDebugException
* @throws PlayerFaultException
*/
public boolean evalIs(Value value, String type) throws PlayerDebugException, PlayerFaultException;
/**
* Evaluate the ActionScript expression "value instanceof type"
*
* @throws PlayerFaultException
* @throws PlayerDebugException
*/
public boolean evalInstanceof(Value value, Value type) throws PlayerDebugException, PlayerFaultException;
/**
* Evaluate the ActionScript expression "value instanceof type"
*
* @throws PlayerFaultException
* @throws PlayerDebugException
*/
public boolean evalInstanceof(Value value, String type) throws PlayerDebugException, PlayerFaultException;
/**
* Evaluate the ActionScript expression "property in object"
*
* @throws PlayerFaultException
* @throws PlayerDebugException
*/
public boolean evalIn(Value property, Value object) throws PlayerDebugException, PlayerFaultException;
/**
* Evaluate the ActionScript expression "value as type"
*
* @throws PlayerDebugException
* @throws PlayerFaultException
*/
public Value evalAs(Value value, Value type) throws PlayerDebugException, PlayerFaultException;
/**
* Returns whether the target player supports watchpoints.
* @see #setWatch(Value, String, int)
*/
public boolean supportsWatchpoints();
/**
* 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.
*/
public Exception getDisconnectCause();
/**
* Set an exception breakpoint. Returns true if succeeded.
* @param exceptionClass
* @return
* @throws NoResponseException
* @throws NotConnectedException
*/
public boolean setExceptionBreakpoint(String exceptionClass) throws NoResponseException, NotConnectedException;
/**
* Clears an exception breakpoint. Returns true if succeeded.
* @param exceptionClass
* @return
* @throws NoResponseException
* @throws NotConnectedException
*/
public boolean clearExceptionBreakpoint(String exceptionClass) throws NoResponseException, NotConnectedException;
// Concurrency begin
/**
* Returns whether the target player supports concurrency.
* @see #setActiveIsolate(Value)
*/
public boolean supportsConcurrency();
/**
* Get an array of all workers that the debugger knows of.
*/
public Isolate[] getWorkers();
/**
* 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.
*/
public Isolate[] refreshWorkers() throws NotSupportedException, NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Return the worker specific session object that can be used
* to communicate with that worker.
*/
public IsolateSession getWorkerSession(int isolateId);
/**
*
* 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.
*
* @param launcher
* ILauncher instance used to launch & terminate the process.
*/
public void setLauncher(ILauncher launcher);
}