/*
 * 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);

}