553N/A * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 553N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 553N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A virtual machine targeted for debugging. 0N/A * More precisely, a {@link Mirror mirror} representing the 0N/A * composite state of the target VM. 0N/A * All other mirrors are associated with an instance of this 0N/A * interface. Access to all other mirrors is achieved 0N/A * directly or indirectly through an instance of this 0N/A * Access to global VM properties and control of VM execution 0N/A * are supported directly by this interface. 0N/A * Instances of this interface are created by instances of 0N/A * {@link com.sun.jdi.connect.Connector}. For example, 0N/A * an {@link com.sun.jdi.connect.AttachingConnector AttachingConnector} * attaches to a target VM and returns its virtual machine mirror. * A Connector will typically create a VirtualMachine by invoking * the VirtualMachineManager's {@link * com.sun.jdi.VirtualMachineManager#createVirtualMachine(Connection)} * createVirtualMachine(Connection) method. * Note that a target VM launched by a launching connector is not * guaranteed to be stable until after the {@link com.sun.jdi.event.VMStartEvent} has been * Any method on <code>VirtualMachine</code> which * takes <code>VirtualMachine</code> as an parameter may throw * {@link com.sun.jdi.VMDisconnectedException} if the target VM is * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is * available to be read from the {@link com.sun.jdi.event.EventQueue}. * Any method on <code>VirtualMachine</code> which * takes <code>VirtualMachine</code> as an parameter may throw * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory. * Returns the loaded reference types that * match a given name. The name must be fully qualified * (for example, java.lang.String). The returned list * will contain a {@link ReferenceType} for each class * or interface found with the given name. The search * is confined to loaded classes only; no attempt is made * to load a class of the given name. * The returned list will include reference types * loaded at least to the point of preparation and * types (like array) for which preparation is * @return a list of {@link ReferenceType} objects, each * mirroring a type in the target VM with the given name. * Returns all loaded types. For each loaded type in the target * VM a {@link ReferenceType} will be placed in the returned list. * The list will include ReferenceTypes which mirror classes, * interfaces, and array types. * The returned list will include reference types * loaded at least to the point of preparation and * types (like array) for which preparation is * @return a list of {@link ReferenceType} objects, each mirroring * a loaded type in the target VM. * All classes given are redefined according to the * definitions supplied. A method in a redefined class * is called 'equivalent' (to the old version of the * <LI>their bytecodes are the same except for indicies into * <LI>the referenced constants are equal. * Otherwise, the new method is called 'non-equivalent'. * If a redefined method has active stack frames, those active * frames continue to run the bytecodes of the previous version of the * method. If the new version of such a method is non-equivalent, * then a method from one of these active frames is called 'obsolete' and * {@link Method#isObsolete Method.isObsolete()} * will return true when called on one of these methods. * If resetting such a frame is desired, use * {@link ThreadReference#popFrames ThreadReference.popFrames(StackFrame)} * to pop the old obsolete method execution from the stack. * New invocations of redefined methods will always invoke the new versions. * This function does not cause any initialization except * that which would occur under the customary JVM semantics. * In other words, redefining a class does not cause * its initializers to be run. The values of preexisting * static variables will remain as they were prior to the * call. However, completely uninitialized (new) static * variables will be assigned their default value. * If a redefined class has instances then all those * instances will have the fields defined by the redefined * class at the completion of the call. Preexisting fields * will retain their previous values. Any new fields will * have their default values; no instance initializers or * Threads need not be suspended. * No events are generated by this function. * All breakpoints in the redefined classes are deleted. * Not all target virtual machines support this operation. * Use {@link #canRedefineClasses() canRedefineClasses()} * to determine if the operation is supported. * Use {@link #canAddMethod() canAddMethod()} * to determine if the redefinition can add methods. * Use {@link #canUnrestrictedlyRedefineClasses() canUnrestrictedlyRedefineClasses()} * to determine if the redefinition can change the schema, * delete methods, change the class hierarchy, etc. * @param classToBytes A map from {@link ReferenceType} * The bytes represent the new class definition and * are in Java Virtual Machine class file format. * @throws java.lang.UnsupportedOperationException if * the target virtual machine does not support this * <LI>If {@link #canRedefineClasses() canRedefineClasses()} * is false any call of this method will throw this exception. * <LI>If {@link #canAddMethod() canAddMethod()} is false * attempting to add a method will throw this exception. * <LI>If {@link #canUnrestrictedlyRedefineClasses() * canUnrestrictedlyRedefineClasses()} * is false, attempting any of the following will throw * <LI>changing the schema (the fields) * <LI>changing the hierarchy (subclasses, interfaces) * <LI>changing class modifiers * <LI>changing method modifiers * @throws java.lang.NoClassDefFoundError if the bytes * don't correspond to the reference type (the names * @throws java.lang.VerifyError if a "verifier" detects * that a class, though well formed, contains an internal * inconsistency or security problem. * @throws java.lang.ClassFormatError if the bytes * do not represent a valid class. * @throws java.lang.ClassCircularityError if a * circularity has been detected while initializing a class. * @throws java.lang.UnsupportedClassVersionError if the * major and minor version numbers in bytes * are not supported by the VM. * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. * @see ThreadReference#popFrames * @see #canRedefineClasses * @see #canUnrestrictedlyRedefineClasses * Returns a list of the currently running threads. For each * running thread in the target VM, a {@link ThreadReference} * that mirrors it is placed in the list. * The returned list contains threads created through * java.lang.Thread, all native threads attached to * the target VM through JNI, and system threads created * by the target VM. Thread objects that have * (see {@link java.lang.Thread#start Thread.start()}) * and thread objects that have * completed their execution are not included in the returned list. * @return a list of {@link ThreadReference} objects, one for each * running thread in the mirrored VM. * Suspends the execution of the application running in this * virtual machine. All threads currently running will be suspended. * Unlike {@link java.lang.Thread#suspend Thread.suspend()}, * suspends of both the virtual machine and individual threads are * counted. Before a thread will run again, it must be resumed * (through {@link #resume} or {@link ThreadReference#resume}) * the same number of times it has been suspended. * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. * Continues the execution of the application running in this * virtual machine. All threads are resumed as documented in * {@link ThreadReference#resume}. * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. * Returns each thread group which does not have a parent. For each * top level thread group a {@link ThreadGroupReference} is placed in the * This command may be used as the first step in building a tree * (or trees) of the existing thread groups. * @return a list of {@link ThreadGroupReference} objects, one for each * top level thread group. * Returns the event queue for this virtual machine. * A virtual machine has only one {@link EventQueue} object, this * method will return the same instance each time it * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. * @return the {@link EventQueue} for this virtual machine. * Returns the event request manager for this virtual machine. * The {@link EventRequestManager} controls user settable events * A virtual machine has only one {@link EventRequestManager} object, * this method will return the same instance each time it * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. * @return the {@link EventRequestManager} for this virtual machine. * Creates a {@link BooleanValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value a boolean for which to create the value * @return the {@link BooleanValue} for the given boolean. * Creates a {@link ByteValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value a byte for which to create the value * @return the {@link ByteValue} for the given byte. * Creates a {@link CharValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value a char for which to create the value * @return the {@link CharValue} for the given char. * Creates a {@link ShortValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value a short for which to create the value * @return the {@link ShortValue} for the given short. * Creates an {@link IntegerValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value an int for which to create the value * @return the {@link IntegerValue} for the given int. * Creates a {@link LongValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value a long for which to create the value * @return the {@link LongValue} for the given long. * Creates a {@link FloatValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value a float for which to create the value * @return the {@link FloatValue} for the given float. * Creates a {@link DoubleValue} for the given value. This value * can be used for setting and comparing against a value retrieved * from a variable or field in this virtual machine. * @param value a double for which to create the value * @return the {@link DoubleValue} for the given double. * Creates a string in this virtual machine. * The created string can be used for setting and comparing against * a string value retrieved from a variable or field in this * @param value the string to be created * @return a {@link StringReference} that mirrors the newly created * string in the target VM. * @throws VMCannotBeModifiedException if the VirtualMachine is read-only * -see {@link VirtualMachine#canBeModified()}. * Creates a {@link VoidValue}. This value * can be passed to {@link ThreadReference#forceEarlyReturn} * when a void method is to be exited. * @return the {@link VoidValue}. * Returns the {@link java.lang.Process} object for this * virtual machine if launched * by a {@link com.sun.jdi.connect.LaunchingConnector} * @return the {@link java.lang.Process} object for this virtual * machine, or null if it was not launched by a * {@link com.sun.jdi.connect.LaunchingConnector}. * @throws VMCannotBeModifiedException if the VirtualMachine is read-only * -see {@link VirtualMachine#canBeModified()}. * Invalidates this virtual machine mirror. * The communication channel to the target VM is closed, and * the target VM prepares to accept another subsequent connection * from this debugger or another debugger, including the * <li>All event requests are cancelled. * <li>All threads suspended by {@link #suspend} or by * {@link ThreadReference#suspend} are resumed as many * times as necessary for them to run. * <li>Garbage collection is re-enabled in all cases where it was * disabled through {@link ObjectReference#disableCollection}. * Any current method invocations executing in the target VM * are continued after the disconnection. Upon completion of any such * method invocation, the invoking thread continues from the * location where it was originally stopped. * Resources originating in * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) * Causes the mirrored VM to terminate with the given error code. * All resources associated with this VirtualMachine are freed. * If the mirrored VM is remote, the communication channel * to it will be closed. Resources originating in * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) * Threads running in the mirrored VM are abruptly terminated. * A thread death exception is not thrown and * finally blocks are not run. * @param exitCode the exit code for the target VM. On some platforms, * the exit code might be truncated, for example, to the lower order 8 bits. * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. * Determines if the target VM supports watchpoints * for field modification. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports watchpoints * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the retrieval * of a method's bytecodes. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the query * of the synthetic attribute of a method or field. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the retrieval * of the monitors owned by a thread. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the retrieval * of the monitor for which a thread is currently waiting. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the retrieval * of the monitor information for an object. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports filtering * events by specific instance object. For example, * see {@link com.sun.jdi.request.BreakpointRequest#addInstanceFilter}. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports any level * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the addition * of methods when performing class redefinition. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports unrestricted * changes when performing class redefinition. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports popping * frames of a threads stack. * @see ThreadReference#popFrames * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports getting * the source debug extension. * @see ReferenceType#sourceDebugExtension * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the creation of * {@link com.sun.jdi.request.VMDeathRequest}s. * @see com.sun.jdi.request.EventRequestManager#createVMDeathRequest * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the inclusion of return values * {@link com.sun.jdi.event.MethodExitEvent}s. * @see com.sun.jdi.request.EventRequestManager#createMethodExitRequest * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the accessing of class instances, * instance counts, and referring objects. * @see ReferenceType#instances(long) * @see ObjectReference#referringObjects(long) * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the filtering of * class prepare events by source name. * see {@link com.sun.jdi.request.ClassPrepareRequest#addSourceNameFilter}. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the forcing of a method to * @see ThreadReference#forceEarlyReturn(Value) * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM is a read-only VM. If a method which * would modify the state of the VM is called on a read-only VM, * then {@link VMCannotBeModifiedException} is thrown. * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports the creation of * {@link com.sun.jdi.request.MonitorContendedEnterRequest}s. * {@link com.sun.jdi.request.MonitorContendedEnteredRequest}s. * {@link com.sun.jdi.request.MonitorWaitRequest}s. * {@link com.sun.jdi.request.MonitorWaitedRequest}s. * @see com.sun.jdi.request.EventRequestManager#createMonitorContendedEnterRequest * @see com.sun.jdi.request.EventRequestManager#createMonitorContendedEnteredRequest * @see com.sun.jdi.request.EventRequestManager#createMonitorWaitRequest * @see com.sun.jdi.request.EventRequestManager#createMonitorWaitedRequest * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports getting which * frame has acquired a monitor. * @see com.sun.jdi.ThreadReference#ownedMonitorsAndFrames * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports reading class file * major and minor versions. * @see ReferenceType#majorVersion() * @see ReferenceType#minorVersion() * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Determines if the target VM supports getting constant pool * information of a class. * @see ReferenceType#constantPoolCount() * @see ReferenceType#constantPool() * @return <code>true</code> if the feature is supported, * <code>false</code> otherwise. * Set this VM's default stratum (see {@link Location} for a * discussion of strata). Overrides the per-class default set * Affects location queries (such as, * {@link Location#sourceName()}) * and the line boundaries used in * @param stratum the stratum to set as VM default, * or null to use per-class defaults. * @throws java.lang.UnsupportedOperationException if the * target virtual machine does not support this operation. * Return this VM's default stratum. * @see #setDefaultStratum(String) * @see ReferenceType#defaultStratum() * @return <code>null</code> (meaning that the per-class * default - {@link ReferenceType#defaultStratum()} - * should be used) unless the default stratum has been * {@link #setDefaultStratum(String)}. * Returns the number of instances of each ReferenceType in the 'refTypes' * Only instances that are reachable for the purposes of garbage collection * Not all target virtual machines support this operation. * Use {@link VirtualMachine#canGetInstanceInfo()} * to determine if the operation is supported. * @see ReferenceType#instances(long) * @see ObjectReference#referringObjects(long) * @param refTypes the list of {@link ReferenceType} objects for which counts * @return an array of <code>long</code> containing one element for each * element in the 'refTypes' list. Element i of the array contains * the number of instances in the target VM of the ReferenceType at * position i in the 'refTypes' list. * If the 'refTypes' list is empty, a zero-length array is returned. * If a ReferenceType in refTypes has been garbage collected, zero * is returned for its instance count. * @throws java.lang.UnsupportedOperationException if * the target virtual machine does not support this * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()} * @throws NullPointerException if the 'refTypes' list is null. * Returns text information on the target VM and the * debugger support that mirrors it. No specific format * for this information is guaranteed. * Typically, this string contains version information for the * target VM and debugger interfaces. * More precise information * on VM and JDI versions is available through * {@link #version}, {@link VirtualMachineManager#majorInterfaceVersion}, * and {@link VirtualMachineManager#minorInterfaceVersion} * @return the description. * Returns the version of the Java Runtime Environment in the target * VM as reported by the property <code>java.version</code>. * For obtaining the JDI interface version, use * {@link VirtualMachineManager#majorInterfaceVersion} * and {@link VirtualMachineManager#minorInterfaceVersion} * @return the target VM version. * Returns the name of the target VM as reported by the * property <code>java.vm.name</code>. * @return the target VM name. /** All tracing is disabled. */ /** Tracing enabled for JDWP packets sent to target VM. */ /** Tracing enabled for JDWP packets received from target VM. */ /** Tracing enabled for internal event handling. */ /** Tracing enabled for internal managment of reference types. */ /** Tracing enabled for internal management of object references. */ /** All tracing is enabled. */ * Traces the activities performed by the com.sun.jdi implementation. * All trace information is output to System.err. The given trace * flags are used to limit the output to only the information * desired. The given flags are in effect and the corresponding * trace will continue until the next call to * Output is implementation dependent and trace mode may be ignored. * @param traceFlags identifies which kinds of tracing to enable.