/*
 * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 *
 */

package sun.jvm.hotspot.debugger;

import java.util.*;
import sun.jvm.hotspot.debugger.cdbg.CDebugger;

public interface Debugger extends SymbolLookup, ThreadAccess {
  
Indicates whether this underlying debugger can provide a list of
currently-running processes. /** Indicates whether this underlying debugger can provide a list of
      currently-running processes. */
  public boolean hasProcessList() throws DebuggerException;

  
Provide a snapshot of the list of currently-running processes in
the form of a List of ProcessInfo objects. Must only be called
if hasProcessList(), above, returns true. /** Provide a snapshot of the list of currently-running processes in
      the form of a List of ProcessInfo objects. Must only be called
      if hasProcessList(), above, returns true. */
  public List getProcessList() throws DebuggerException;

  
If an error occurs during attachment (i.e., "no such process"),
the thrown DebuggerException will contain a description of the
error in its message string. /** If an error occurs during attachment (i.e., "no such process"),
      the thrown DebuggerException will contain a description of the
      error in its message string. */
  public void attach(int processID) throws DebuggerException;

  
This attaches the debugger to the given coreFileName, which is
assumed to have been generated from the specified
executableName. If an error occurs during loading of the core
file (i.e., "no such file"), the thrown DebuggerException will
contain a description of the error in its message string. /** This attaches the debugger to the given coreFileName, which is
      assumed to have been generated from the specified
      executableName. If an error occurs during loading of the core
      file (i.e., "no such file"), the thrown DebuggerException will
      contain a description of the error in its message string. */
  public void attach(String executableName, String coreFileName)
    throws DebuggerException;

  
Detach from the remote process. Returns false if not currently
attached. /** Detach from the remote process. Returns false if not currently
      attached. */
  public boolean detach() throws DebuggerException;

  
Parse an address from a hex string in the format "0xFFFFFFFF".
The length of the address (i.e., 32 or 64 bits) is platform
dependent. This method should ONLY be used by routines which
need to interact with the user and parse a string entered by
hand; for example, a graphical user interface. This routine
should NOT be used to subvert the current safety mechanisms in
the system which prevent arbitrary conversion from Address to
long and back. /** Parse an address from a hex string in the format "0xFFFFFFFF".
      The length of the address (i.e., 32 or 64 bits) is platform
      dependent. This method should ONLY be used by routines which
      need to interact with the user and parse a string entered by
      hand; for example, a graphical user interface. This routine
      should NOT be used to subvert the current safety mechanisms in
      the system which prevent arbitrary conversion from Address to
      long and back. */
  public Address parseAddress(String addressString)
    throws NumberFormatException, DebuggerException;

  
Returns the 64-bit value of an Address. This method should ONLY
be used when implementing a debugger which needs to interface to
C and which needs a unique identifier for certain objects. /** Returns the 64-bit value of an Address. This method should ONLY
      be used when implementing a debugger which needs to interface to
      C and which needs a unique identifier for certain objects. */
  public long getAddressValue(Address addr) throws DebuggerException;

  
Support for remote debugging. Get the name of the operating
system on which this debugger is running (to be able to properly
configure the local system). Typical return values are
"solaris", "linux", "win32"; see utilities/PlatformInfo.java. /** Support for remote debugging. Get the name of the operating
      system on which this debugger is running (to be able to properly
      configure the local system). Typical return values are
      "solaris", "linux", "win32"; see utilities/PlatformInfo.java. */
  public String getOS() throws DebuggerException;

  
Support for remote debugging. Get the name of the CPU type on
which this debugger is running (to be able to properly configure
the local system). Typical return values are "sparc", "x86"; see
utilities/PlatformInfo.java. /** Support for remote debugging. Get the name of the CPU type on
      which this debugger is running (to be able to properly configure
      the local system). Typical return values are "sparc", "x86"; see
      utilities/PlatformInfo.java. */
  public String getCPU() throws DebuggerException;

  
Retrieve the machine description for the underlying hardware for
the cases in which we need to do, for example, machine-dependent
byte swapping /** Retrieve the machine description for the underlying hardware for
      the cases in which we need to do, for example, machine-dependent
      byte swapping */
  public MachineDescription getMachineDescription() throws DebuggerException;

  
Find out whether this debugger has a console available on which
commands can be executed; see executeCommandOnConsole, below.
This is an interim routine designed to allow access to the
underlying dbx process on Solaris until we have disassembly,
etc. in the SA. /** Find out whether this debugger has a console available on which
      commands can be executed; see executeCommandOnConsole, below.
      This is an interim routine designed to allow access to the
      underlying dbx process on Solaris until we have disassembly,
      etc. in the SA. */
  public boolean hasConsole() throws DebuggerException;

  
If the underlying debugger has a console (as dbx does), this
provides access to it. Takes in a platform-dependent String,
executes it on the debugger's console, and returns any output as
a String. /** If the underlying debugger has a console (as dbx does), this
      provides access to it. Takes in a platform-dependent String,
      executes it on the debugger's console, and returns any output as
      a String. */
  public String consoleExecuteCommand(String cmd) throws DebuggerException;

  
If the underlying debugger has a console, this returns the
debugger-specific prompt which should be displayed. /** If the underlying debugger has a console, this returns the
      debugger-specific prompt which should be displayed. */
  public String getConsolePrompt() throws DebuggerException;

  
If this platform supports C/C++ debugging via the CDebugger
interface, returns a CDebugger object; otherwise returns
null. /** If this platform supports C/C++ debugging via the CDebugger
      interface, returns a CDebugger object; otherwise returns
      null. */
  public CDebugger getCDebugger() throws DebuggerException;

  
the following methods are intended only for RemoteDebuggerClient /** the following methods are intended only for RemoteDebuggerClient */
  public long getJBooleanSize();
  public long getJByteSize();
  public long getJCharSize();
  public long getJDoubleSize();
  public long getJFloatSize();
  public long getJIntSize();
  public long getJLongSize();
  public long getJShortSize();
  public long getHeapOopSize();
  public long getNarrowOopBase();
  public int  getNarrowOopShift();
  public long getKlassPtrSize();
  public long getNarrowKlassBase();
  public int  getNarrowKlassShift();

  public ReadResult readBytesFromProcess(long address, long numBytes)
    throws DebuggerException;

  public void writeBytesToProcess(long address, long numBytes, byte[] data)
    throws UnmappedAddressException, DebuggerException;
}