/*

 * Copyright (c) 1998, 2019, 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.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * 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.

 */

JDWP "Java(tm) Debug Wire Protocol"

(CommandSet VirtualMachine=1

    (Command Version=1

        "Returns the JDWP version implemented by the target VM. "

        "The version string format is implementation dependent. "

        (Out

        )

        (Reply

            (string description "Text information on the VM version")

            (int    jdwpMajor   "Major JDWP Version number")

            (int    jdwpMinor   "Minor JDWP Version number")

            (string vmVersion   "Target VM JRE version, as in the java.version property")

            (string vmName      "Target VM name, as in the java.vm.name property")

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command ClassesBySignature=2

        "Returns reference types for all the classes loaded by the target VM "

        "which match the given signature. "

        "Multple reference types will be returned if two or more class "

        "loaders have loaded a class of the same name. "

        "The search is confined to loaded classes only; no attempt is made "

        "to load a class of the given signature. "

        (Out

            (string signature "JNI signature of the class to find "

                              "(for example, \"Ljava/lang/String;\"). "

            )

        )

        (Reply

            (Repeat classes "Number of reference types that follow."

                (Group ClassInfo

                    (byte refTypeTag  "<a href=\"#JDWP_TypeTag\">Kind</a> "

                                      "of following reference type. ")

                    (referenceTypeID typeID "Matching loaded reference type")

                    (int status "The current class "

                                "<a href=\"#JDWP_ClassStatus\">status.</a> ")

                )

            )

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command AllClasses=3

        "Returns reference types for all classes currently loaded by the "

        "target VM."

        (Out

        )

        (Reply

            (Repeat classes "Number of reference types that follow."

                (Group ClassInfo

                    (byte refTypeTag  "<a href=\"#JDWP_TypeTag\">Kind</a> "

                                      "of following reference type. ")

                    (referenceTypeID typeID "Loaded reference type")

                    (string signature

                                "The JNI signature of the loaded reference type")

                    (int status "The current class "

                                "<a href=\"#JDWP_ClassStatus\">status.</a> ")

                )

            )

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command AllThreads=4

        "Returns all threads currently running in the target VM . "

        "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. Threads that have not yet been started "

        "and threads that have completed their execution are not "

        "included in the returned list. "

        (Out

        )

        (Reply

            (Repeat threads "Number of threads that follow."

                (threadObject thread "A running thread")

            )

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command TopLevelThreadGroups=5

        "Returns all thread groups that do not have a parent. This command "

        "may be used as the first step in building a tree (or trees) of the "

        "existing thread groups."

        (Out

        )

        (Reply

            (Repeat groups "Number of thread groups that follow."

                (threadGroupObject group "A top level thread group")

            )

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command Dispose=6

        "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 "

        "following tasks: "

        "<ul>"

        "<li>All event requests are cancelled. "

        "<li>All threads suspended by the thread-level "

        "<a href=\"#JDWP_ThreadReference_Resume\">resume</a> command "

        "or the VM-level "

        "<a href=\"#JDWP_VirtualMachine_Resume\">resume</a> command "

        "are resumed as many times as necessary for them to run. "

        "<li>Garbage collection is re-enabled in all cases where it was "

        "<a href=\"#JDWP_ObjectReference_DisableCollection\">disabled</a> "

        "</ul>"

        "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. "

        "<p>"

        "Resources originating in  "

        "this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) "

        "will become invalid. "

        (Out

        )

        (Reply

        )

        (ErrorSet

        )

    )

    (Command IDSizes=7

        "Returns the sizes of variably-sized data types in the target VM."

        "The returned values indicate the number of bytes used by the "

        "identifiers in command and reply packets."

        (Out

        )

        (Reply

            (int fieldIDSize "fieldID size in bytes ")

            (int methodIDSize "methodID size in bytes ")

            (int objectIDSize "objectID size in bytes ")

            (int referenceTypeIDSize "referenceTypeID size in bytes ")

            (int frameIDSize "frameID size in bytes ")

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command Suspend=8

        "Suspends the execution of the application running in the target "

        "VM. All Java threads currently running will be suspended. "

        "<p>"

        "Unlike java.lang.Thread.suspend, "

        "suspends of both the virtual machine and individual threads are "

        "counted. Before a thread will run again, it must be resumed through "

        "the <a href=\"#JDWP_VirtualMachine_Resume\">VM-level resume</a> command "

        "or the <a href=\"#JDWP_ThreadReference_Resume\">thread-level resume</a> command "

        "the same number of times it has been suspended. "

        (Out

        )

        (Reply

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command Resume=9

        "Resumes execution of the application after the suspend "

        "command or an event has stopped it. "

        "Suspensions of the Virtual Machine and individual threads are "

        "counted. If a particular thread is suspended n times, it must "

        "resumed n times before it will continue. "

        (Out

        )

        (Reply

        )

        (ErrorSet

        )

    )

    (Command Exit=10

        "Terminates the target VM with the given exit code. "

        "On some platforms, the exit code might be truncated, for "

        "example, to the low order 8 bits. "

        "All ids previously returned from the target VM become invalid. "

        "Threads running in the VM are abruptly terminated. "

        "A thread death exception is not thrown and "

        "finally blocks are not run."

        (Out

            (int exitCode "the exit code")

        )

        (Reply

        )

        (ErrorSet

        )

    )

    (Command CreateString=11

        "Creates a new string object in the target VM and returns "

        "its id. "

        (Out

            (string utf "UTF-8 characters to use in the created string. ")

        )

        (Reply

            (stringObject stringObject

                "Created string (instance of java.lang.String) ")

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command Capabilities=12

        "Retrieve this VM's capabilities. The capabilities are returned "

        "as booleans, each indicating the presence or absence of a "

        "capability. The commands associated with each capability will "

        "return the NOT_IMPLEMENTED error if the cabability is not "

        "available."

        (Out

        )

        (Reply

            (boolean canWatchFieldModification

                     "Can the VM watch field modification, and therefore "

                     "can it send the Modification Watchpoint Event?")

            (boolean canWatchFieldAccess

                     "Can the VM watch field access, and therefore "

                     "can it send the Access Watchpoint Event?")

            (boolean canGetBytecodes

                     "Can the VM get the bytecodes of a given method? ")

            (boolean canGetSyntheticAttribute

                     "Can the VM determine whether a field or method is "

                     "synthetic? (that is, can the VM determine if the "

                     "method or the field was invented by the compiler?) ")

            (boolean canGetOwnedMonitorInfo

                     "Can the VM get the owned monitors infornation for "

                     "a thread?")

            (boolean canGetCurrentContendedMonitor

                     "Can the VM get the current contended monitor of a thread?")

            (boolean canGetMonitorInfo

                     "Can the VM get the monitor information for a given object? ")

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command ClassPaths=13

        "Retrieve the classpath and bootclasspath of the target VM. "

        "If the classpath is not defined, returns an empty list. If the "

        "bootclasspath is not defined returns an empty list."

        (Out

        )

        (Reply

            (string baseDir "Base directory used to resolve relative "

                            "paths in either of the following lists.")

            (Repeat classpaths "Number of paths in classpath."

                (string path "One component of classpath") )

            (Repeat bootclasspaths "Number of paths in bootclasspath."

                (string path "One component of bootclasspath") )

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command DisposeObjects=14

        "Releases a list of object IDs. For each object in the list, the "

        "following applies. "

        "The count of references held by the back-end (the reference "

        "count) will be decremented by refCnt. "

        "If thereafter the reference count is less than "

        "or equal to zero, the ID is freed. "

        "Any back-end resources associated with the freed ID may "

        "be freed, and if garbage collection was "

        "disabled for the object, it will be re-enabled. "

        "The sender of this command "

        "promises that no further commands will be sent "

        "referencing a freed ID.

        "<p>"

        "Use of this command is not required. If it is not sent, "

        "resources associated with each ID will be freed by the back-end "

        "at some time after the corresponding object is garbage collected. "

        "It is most useful to use this command to reduce the load on the "

        "back-end if a very large number of "

        "objects has been retrieved from the back-end (a large array, "

        "for example) but may not be garbage collected any time soon. "

        "<p>"

        "IDs may be re-used by the back-end after they "

        "have been freed with this command."

        "This description assumes reference counting, "

        "a back-end may use any implementation which operates "

        "equivalently. "

        (Out

            (Repeat requests "Number of object dispose requests that follow"

                (Group Request

                    (object object "The object ID")

                    (int refCnt "The number of times this object ID has been "

                                "part of a packet received from the back-end. "

                                "An accurate count prevents the object ID "

                                "from being freed on the back-end if "

                                "it is part of an incoming packet, not yet "

                                "handled by the front-end.")

                )

            )

        )

        (Reply

        )

        (ErrorSet

        )

    )

    (Command HoldEvents=15

        "Tells the target VM to stop sending events. Events are not discarded; "

        "they are held until a subsequent ReleaseEvents command is sent. "

        "This command is useful to control the number of events sent "

        "to the debugger VM in situations where very large numbers of events "

        "are generated. "

        "While events are held by the debugger back-end, application "

        "execution may be frozen by the debugger back-end to prevent "

        "buffer overflows on the back end.

        "Responses to commands are never held and are not affected by this

        "command. If events are already being held, this command is "

        "ignored."

        (Out

        )

        (Reply

        )

        (ErrorSet

        )

    )

    (Command ReleaseEvents=16

        "Tells the target VM to continue sending events. This command is "

        "used to restore normal activity after a HoldEvents command. If "

        "there is no current HoldEvents command in effect, this command is "

        "ignored."

        (Out

        )

        (Reply

        )

        (ErrorSet

        )

    )

    (Command CapabilitiesNew=17

        "Retrieve all of this VM's capabilities. The capabilities are returned "

        "as booleans, each indicating the presence or absence of a "

        "capability. The commands associated with each capability will "

        "return the NOT_IMPLEMENTED error if the cabability is not "

        "available."

        "Since JDWP version 1.4."

        (Out

        )

        (Reply

            (boolean canWatchFieldModification

                     "Can the VM watch field modification, and therefore "

                     "can it send the Modification Watchpoint Event?")

            (boolean canWatchFieldAccess

                     "Can the VM watch field access, and therefore "

                     "can it send the Access Watchpoint Event?")

            (boolean canGetBytecodes

                     "Can the VM get the bytecodes of a given method? ")

            (boolean canGetSyntheticAttribute

                     "Can the VM determine whether a field or method is "

                     "synthetic? (that is, can the VM determine if the "

                     "method or the field was invented by the compiler?) ")

            (boolean canGetOwnedMonitorInfo

                     "Can the VM get the owned monitors infornation for "

                     "a thread?")

            (boolean canGetCurrentContendedMonitor

                     "Can the VM get the current contended monitor of a thread?")

            (boolean canGetMonitorInfo

                     "Can the VM get the monitor information for a given object? ")

            (boolean canRedefineClasses

                     "Can the VM redefine classes?")

            (boolean canAddMethod

                     "Can the VM add methods when redefining "

                     "classes?")

            (boolean canUnrestrictedlyRedefineClasses

                     "Can the VM redefine classes "

                     "in ways that are normally restricted?")

            (boolean canPopFrames

                     "Can the VM pop stack frames?")

            (boolean canUseInstanceFilters

                     "Can the VM filter events by specific object?")

            (boolean canGetSourceDebugExtension

                     "Can the VM get the source debug extension?")

            (boolean canRequestVMDeathEvent

                     "Can the VM request VM death events?")

            (boolean canSetDefaultStratum

                     "Can the VM set a default stratum?")

            (boolean canGetInstanceInfo

                     "Can the VM return instances, counts of instances of classes "

                     "and referring objects?")

            (boolean canRequestMonitorEvents

                     "Can the VM request monitor events?")

            (boolean canGetMonitorFrameInfo

                     "Can the VM get monitors with frame depth info?")

            (boolean canUseSourceNameFilters

                     "Can the VM filter class prepare events by source name?")

            (boolean canGetConstantPool

                     "Can the VM return the constant pool information?")

            (boolean canForceEarlyReturn

                     "Can the VM force early return from a method?")

            (boolean reserved22

                     "Reserved for future capability")

            (boolean reserved23

                     "Reserved for future capability")

            (boolean reserved24

                     "Reserved for future capability")

            (boolean reserved25

                     "Reserved for future capability")

            (boolean reserved26

                     "Reserved for future capability")

            (boolean reserved27

                     "Reserved for future capability")

            (boolean reserved28

                     "Reserved for future capability")

            (boolean reserved29

                     "Reserved for future capability")

            (boolean reserved30

                     "Reserved for future capability")

            (boolean reserved31

                     "Reserved for future capability")

            (boolean reserved32

                     "Reserved for future capability")

        )

        (ErrorSet

            (Error VM_DEAD)

        )

    )

    (Command RedefineClasses=18

        "Installs new class definitions. "

        "If there are active stack frames in methods of the redefined classes in the "

        "target VM then those active frames continue to run the bytecodes of the "

        "original method. These methods are considered obsolete - see "

        "<a href=\"#JDWP_Method_IsObsolete\">IsObsolete</a>. The methods in the "

        "redefined classes will be used for new invokes in the target VM. "

        "The original method ID refers to the redefined method. "

        "All breakpoints in the redefined classes are cleared."

        "If resetting of stack frames is desired, the "

        "<a href=\"#JDWP_StackFrame_PopFrames\">PopFrames</a> command can be used "

        "to pop frames with obsolete methods."

        "<p>"

        "Unless the canUnrestrictedlyRedefineClasses capability is present the following "

        "redefinitions are restricted: "

        "<ul>"

        "<li>changing the schema (the fields)</li>"

        "<li>changing the hierarchy (superclasses, interfaces)</li>"

        "<li>deleting a method</li>"

        "<li>changing class modifiers</li>"

        "<li>changing method modifiers</li>"

        "<li>changing the <code>NestHost</code> or <code>NestMembers</code> class attributes</li>"

        "</ul>"

        "<p>"

        "Requires canRedefineClasses capability - see "

        "<a href=\"#JDWP_VirtualMachine_CapabilitiesNew\">CapabilitiesNew</a>. "

        "In addition to the canRedefineClasses capability, the target VM must "

        "have the canAddMethod capability to add methods when redefining classes, "

        "or the canUnrestrictedlyRedefineClasses capability to redefine classes in ways "

        "that are normally restricted."

        (Out

            (Repeat classes "Number of reference types that follow."

                (Group ClassDef

                    (referenceType refType "The reference type.")

                    (Repeat classfile "Number of bytes defining class (below)"

                         (byte classbyte "byte in JVM class file "

                                         "format.")

                    )

                )

            )

        )

        (Reply

        )

        (ErrorSet

            (Error INVALID_CLASS    "One of the refTypes is not the ID of a reference "

                                    "type.")

            (Error INVALID_OBJECT   "One of the refTypes is not a known ID.")

            (Error UNSUPPORTED_VERSION)

            (Error INVALID_CLASS_FORMAT)

            (Error CIRCULAR_CLASS_DEFINITION)

            (Error FAILS_VERIFICATION)

            (Error NAMES_DONT_MATCH)

            (Error NOT_IMPLEMENTED  "No aspect of this functionality is implemented "

                                    "(CapabilitiesNew.canRedefineClasses is false)")

            (Error ADD_METHOD_NOT_IMPLEMENTED)

            (Error SCHEMA_CHANGE_NOT_IMPLEMENTED)