1 /*

     2  * Copyright 1998-2006 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

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

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package com.sun.jdi;

    27 

    28 import com.sun.jdi.event.EventQueue;

    29 import com.sun.jdi.request.EventRequestManager;

    30 

    31 import java.util.List;

    32 import java.util.Map;

    33 

    34 /**

    35  * A virtual machine targeted for debugging.

    36  * More precisely, a {@link Mirror mirror} representing the

    37  * composite state of the target VM.

    38  * All other mirrors are associated with an instance of this

    39  * interface.  Access to all other mirrors is achieved

    40  * directly or indirectly through an instance of this

    41  * interface.

    42  * Access to global VM properties and control of VM execution

    43  * are supported directly by this interface.

    44  * <P>

    45  * Instances of this interface are created by instances of

    46  * {@link com.sun.jdi.connect.Connector}. For example,

    47  * an {@link com.sun.jdi.connect.AttachingConnector AttachingConnector}

    48  * attaches to a target VM and returns its virtual machine mirror.

    49  * A Connector will typically create a VirtualMachine by invoking

    50  * the VirtualMachineManager's {@link

    51  * com.sun.jdi.VirtualMachineManager#createVirtualMachine(Connection)}

    52  * createVirtualMachine(Connection) method.

    53  * <p>

    54  * Note that a target VM launched by a launching connector is not

    55  * guaranteed to be stable until after the {@link com.sun.jdi.event.VMStartEvent} has been

    56  * received.

    57  * <p>

    58  * Any method on <code>VirtualMachine</code> which

    59  * takes <code>VirtualMachine</code> as an parameter may throw

    60  * {@link com.sun.jdi.VMDisconnectedException} if the target VM is

    61  * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is

    62  * available to be read from the {@link com.sun.jdi.event.EventQueue}.

    63  * <p>

    64  * Any method on <code>VirtualMachine</code> which

    65  * takes <code>VirtualMachine</code> as an parameter may throw

    66  * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.

    67  *

    68  * @author Robert Field

    69  * @author Gordon Hirsch

    70  * @author James McIlree

    71  * @since  1.3

    72  */

    73 public interface VirtualMachine extends Mirror {

    74 

    75     /**

    76      * Returns the loaded reference types that

    77      * match a given name. The name must be fully qualified

    78      * (for example, java.lang.String). The returned list

    79      * will contain a {@link ReferenceType} for each class

    80      * or interface found with the given name. The search

    81      * is confined to loaded classes only; no attempt is made

    82      * to load a class of the given name.

    83      * <P>

    84      * The returned list will include reference types

    85      * loaded at least to the point of preparation and

    86      * types (like array) for which preparation is

    87      * not defined.

    88      *

    89      * @param className the class/interface name to search for

    90      * @return a list of {@link ReferenceType} objects, each

    91      * mirroring a type in the target VM with the given name.

    92      */

    93     List<ReferenceType> classesByName(String className);

    94 

    95     /**

    96      * Returns all loaded types. For each loaded type in the target

    97      * VM a {@link ReferenceType} will be placed in the returned list.

    98      * The list will include ReferenceTypes which mirror classes,

    99      * interfaces, and array types.

   100      * <P>

   101      * The returned list will include reference types

   102      * loaded at least to the point of preparation and

   103      * types (like array) for which preparation is

   104      * not defined.

   105      *

   106      * @return a list of {@link ReferenceType} objects, each mirroring

   107      * a loaded type in the target VM.

   108      */

   109     List<ReferenceType> allClasses();

   110 

   111     /**

   112      * All classes given are redefined according to the

   113      * definitions supplied.  A method in a redefined class

   114      * is called 'equivalent' (to the old version of the

   115      * method) if

   116      * <UL>

   117      * <LI>their bytecodes are the same except for indicies into

   118      *   the constant pool, and

   119      * <LI>the referenced constants are equal.

   120      * </UL>

   121      * Otherwise, the new method is called 'non-equivalent'.

   122      * If a redefined method has active stack frames, those active

   123      * frames continue to run the bytecodes of the previous version of the

   124      * method.  If the new version of such a method is non-equivalent,

   125      * then a method from one of these active frames is called 'obsolete' and

   126      * {@link Method#isObsolete Method.isObsolete()}

   127      * will return true when called on one of these methods.

   128      * If resetting such a frame is desired, use

   129      * {@link ThreadReference#popFrames ThreadReference.popFrames(StackFrame)}

   130      * to pop the old obsolete method execution from the stack.

   131      * New invocations of redefined methods will always invoke the new versions.

   132      * <p>

   133      * This function does not cause any initialization except

   134      * that which would occur under the customary JVM semantics.

   135      * In other words, redefining a class does not cause

   136      * its initializers to be run. The values of preexisting

   137      * static variables will remain as they were prior to the

   138      * call. However, completely uninitialized (new) static

   139      * variables will be assigned their default value.

   140      * <p>

   141      * If a redefined class has instances then all those

   142      * instances will have the fields defined by the redefined

   143      * class at the completion of the call. Preexisting fields

   144      * will retain their previous values. Any new fields will

   145      * have their default values; no instance initializers or

   146      * constructors are run.

   147      * <p>

   148      * Threads need not be suspended.

   149      * <p>

   150      * No events are generated by this function.

   151      * <p>

   152      * All breakpoints in the redefined classes are deleted.

   153      * <p>

   154      * Not all target virtual machines support this operation.

   155      * Use {@link #canRedefineClasses() canRedefineClasses()}

   156      * to determine if the operation is supported.

   157      * Use {@link #canAddMethod() canAddMethod()}

   158      * to determine if the redefinition can add methods.

   159      * Use {@link #canUnrestrictedlyRedefineClasses() canUnrestrictedlyRedefineClasses()}

   160      * to determine if the redefinition can change the schema,

   161      * delete methods, change the class hierarchy, etc.

   162      *

   163      * @param classToBytes A map from {@link ReferenceType}

   164      * to array of byte.

   165      * The bytes represent the new class definition and

   166      * are in Java Virtual Machine class file format.

   167      *

   168      * @throws java.lang.UnsupportedOperationException if

   169      * the target virtual machine does not support this

   170      * operation.

   171      * <UL>

   172      * <LI>If {@link #canRedefineClasses() canRedefineClasses()}

   173      * is false any call of this method will throw this exception.

   174      * <LI>If {@link #canAddMethod() canAddMethod()} is false

   175      * attempting to add a method will throw this exception.

   176      * <LI>If {@link #canUnrestrictedlyRedefineClasses()

   177      *            canUnrestrictedlyRedefineClasses()}

   178      * is false, attempting any of the following will throw

   179      * this exception

   180      *   <UL>

   181      *   <LI>changing the schema (the fields)

   182      *   <LI>changing the hierarchy (subclasses, interfaces)

   183      *   <LI>deleting a method

   184      *   <LI>changing class modifiers

   185      *   <LI>changing method modifiers

   186      *   </UL>

   187      * </UL>

   188      *

   189      * @throws java.lang.NoClassDefFoundError if the bytes

   190      * don't correspond to the reference type (the names

   191      * don't match).

   192      *

   193      * @throws java.lang.VerifyError if a "verifier" detects

   194      * that a class, though well formed, contains an internal

   195      * inconsistency or security problem.

   196      *

   197      * @throws java.lang.ClassFormatError if the bytes

   198      * do not represent a valid class.

   199      *

   200      * @throws java.lang.ClassCircularityError if a

   201      * circularity has been detected while initializing a class.

   202      *

   203      * @throws java.lang.UnsupportedClassVersionError if the

   204      * major and minor version numbers in bytes

   205      * are not supported by the VM.

   206      *

   207      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.

   208      *

   209      * @see Method#isObsolete

   210      * @see ThreadReference#popFrames

   211      * @see #canRedefineClasses

   212      * @see #canAddMethod

   213      * @see #canUnrestrictedlyRedefineClasses

   214      *

   215      * @since 1.4

   216      */

   217     void redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes);

   218 

   219     /**

   220      * Returns a list of the currently running threads. For each

   221      * running thread in the target VM, a {@link ThreadReference}

   222      * that mirrors it is placed in the list.

   223      * The returned list contains threads created through

   224      * java.lang.Thread, all native threads attached to

   225      * the target VM through JNI, and system threads created

   226      * by the target VM. Thread objects that have

   227      * not yet been started

   228      * (see {@link java.lang.Thread#start Thread.start()})

   229      * and thread objects that have

   230      * completed their execution are not included in the returned list.

   231      *

   232      * @return a list of {@link ThreadReference} objects, one for each

   233      * running thread in the mirrored VM.

   234      */

   235     List<ThreadReference> allThreads();

   236 

   237     /**

   238      * Suspends the execution of the application running in this

   239      * virtual machine. All threads currently running will be suspended.

   240      * <p>

   241      * Unlike {@link java.lang.Thread#suspend Thread.suspend()},

   242      * suspends of both the virtual machine and individual threads are

   243      * counted. Before a thread will run again, it must be resumed

   244      * (through {@link #resume} or {@link ThreadReference#resume})

   245      * the same number of times it has been suspended.

   246      *

   247      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.

   248      */

   249     void suspend();

   250 

   251     /**

   252      * Continues the execution of the application running in this

   253      * virtual machine. All threads are resumed as documented in

   254      * {@link ThreadReference#resume}.

   255      *

   256      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.

   257      *

   258      * @see #suspend

   259      */

   260     void resume();

   261 

   262     /**

   263      * Returns each thread group which does not have a parent. For each

   264      * top level thread group a {@link ThreadGroupReference} is placed in the

   265      * returned list.

   266      * <p>

   267      * This command may be used as the first step in building a tree

   268      * (or trees) of the existing thread groups.

   269      *

   270      * @return a list of {@link ThreadGroupReference} objects, one for each

   271      * top level thread group.

   272      */

   273     List<ThreadGroupReference> topLevelThreadGroups();

   274 

   275     /**

   276      * Returns the event queue for this virtual machine.

   277      * A virtual machine has only one {@link EventQueue} object, this

   278      * method will return the same instance each time it

   279      * is invoked.

   280      *

   281      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.

   282      *

   283      * @return the {@link EventQueue} for this virtual machine.

   284      */

   285     EventQueue eventQueue();

   286 

   287     /**

   288      * Returns the event request manager for this virtual machine.

   289      * The {@link EventRequestManager} controls user settable events

   290      * such as breakpoints.

   291      * A virtual machine has only one {@link EventRequestManager} object,

   292      * this method will return the same instance each time it

   293      * is invoked.

   294      *

   295      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.

   296      *

   297      * @return the {@link EventRequestManager} for this virtual machine.

   298      */

   299     EventRequestManager eventRequestManager();

   300 

   301     /**

   302      * Creates a {@link BooleanValue} for the given value. This value

   303      * can be used for setting and comparing against a value retrieved

   304      * from a variable or field in this virtual machine.

   305      *

   306      * @param value a boolean for which to create the value

   307      * @return the {@link BooleanValue} for the given boolean.

   308      */

   309     BooleanValue mirrorOf(boolean value);

   310 

   311     /**

   312      * Creates a {@link ByteValue} for the given value. This value

   313      * can be used for setting and comparing against a value retrieved

   314      * from a variable or field in this virtual machine.

   315      *

   316      * @param value a byte for which to create the value

   317      * @return the {@link ByteValue} for the given byte.

   318      */

   319     ByteValue mirrorOf(byte value);

   320 

   321     /**

   322      * Creates a {@link CharValue} for the given value. This value

   323      * can be used for setting and comparing against a value retrieved

   324      * from a variable or field in this virtual machine.

   325      *

   326      * @param value a char for which to create the value

   327      * @return the {@link CharValue} for the given char.

   328      */

   329     CharValue mirrorOf(char value);

   330 

   331     /**

   332      * Creates a {@link ShortValue} for the given value. This value

   333      * can be used for setting and comparing against a value retrieved

   334      * from a variable or field in this virtual machine.

   335      *

   336      * @param value a short for which to create the value

   337      * @return the {@link ShortValue} for the given short.

   338      */

   339     ShortValue mirrorOf(short value);

   340 

   341     /**

   342      * Creates an {@link IntegerValue} for the given value. This value

   343      * can be used for setting and comparing against a value retrieved

   344      * from a variable or field in this virtual machine.

   345      *

   346      * @param value an int for which to create the value

   347      * @return the {@link IntegerValue} for the given int.

   348      */

   349     IntegerValue mirrorOf(int value);

   350 

   351     /**

   352      * Creates a {@link LongValue} for the given value. This value

   353      * can be used for setting and comparing against a value retrieved

   354      * from a variable or field in this virtual machine.

   355      *

   356      * @param value a long for which to create the value

   357      * @return the {@link LongValue} for the given long.

   358      */

   359     LongValue mirrorOf(long value);

   360 

   361     /**

   362      * Creates a {@link FloatValue} for the given value. This value

   363      * can be used for setting and comparing against a value retrieved

   364      * from a variable or field in this virtual machine.

   365      *

   366      * @param value a float for which to create the value

   367      * @return the {@link FloatValue} for the given float.

   368      */

   369     FloatValue mirrorOf(float value);

   370 

   371     /**

   372      * Creates a {@link DoubleValue} for the given value. This value

   373      * can be used for setting and comparing against a value retrieved

   374      * from a variable or field in this virtual machine.

   375      *

   376      * @param value a double for which to create the value

   377      * @return the {@link DoubleValue} for the given double.

   378      */

   379     DoubleValue mirrorOf(double value);

   380 

   381     /**

   382      * Creates a string in this virtual machine.

   383      * The created string can be used for setting and comparing against

   384      * a string value retrieved from a variable or field in this

   385      * virtual machine.

   386      *

   387      * @param value the string to be created

   388      * @return a {@link StringReference} that mirrors the newly created

   389      * string in the target VM.

   390      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only

   391      * -see {@link VirtualMachine#canBeModified()}.

   392      */

   393     StringReference mirrorOf(String value);

   394 

   395 

   396     /**

   397      * Creates a {@link VoidValue}.  This value

   398      * can be passed to {@link ThreadReference#forceEarlyReturn}

   399      * when a void method is to be exited.

   400      *

   401      * @return the {@link VoidValue}.

   402      */

   403     VoidValue mirrorOfVoid();

   404 

   405     /**

   406      * Returns the {@link java.lang.Process} object for this

   407      * virtual machine if launched

   408      * by a {@link com.sun.jdi.connect.LaunchingConnector}

   409      *

   410      * @return the {@link java.lang.Process} object for this virtual

   411      * machine, or null if it was not launched by a

   412      * {@link com.sun.jdi.connect.LaunchingConnector}.

   413      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only

   414      * -see {@link VirtualMachine#canBeModified()}.

   415      */

   416     Process process();

   417 

   418     /**

   419      * Invalidates this virtual machine mirror.

   420      * The communication channel to the target VM is closed, and

   421      * the target VM prepares to accept another subsequent connection

   422      * from this debugger or another debugger, including the

   423      * following tasks:

   424      * <ul>

   425      * <li>All event requests are cancelled.

   426      * <li>All threads suspended by {@link #suspend} or by

   427      * {@link ThreadReference#suspend} are resumed as many

   428      * times as necessary for them to run.

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

   430      * disabled through {@link ObjectReference#disableCollection}.

   431      * </ul>

   432      * Any current method invocations executing in the target VM

   433      * are continued after the disconnection. Upon completion of any such

   434      * method invocation, the invoking thread continues from the

   435      * location where it was originally stopped.

   436      * <p>

   437      * Resources originating in

   438      * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)

   439      * will become invalid.

   440      */

   441     void dispose();

   442 

   443     /**

   444      * Causes the mirrored VM to terminate with the given error code.

   445      * All resources associated with this VirtualMachine are freed.

   446      * If the mirrored VM is remote, the communication channel

   447      * to it will be closed. Resources originating in

   448      * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)

   449      * will become invalid.

   450      * <p>

   451      * Threads running in the mirrored VM are abruptly terminated.

   452      * A thread death exception is not thrown and

   453      * finally blocks are not run.

   454      *

   455      * @param exitCode the exit code for the target VM.  On some platforms,

   456      * the exit code might be truncated, for example, to the lower order 8 bits.

   457      *

   458      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.

   459      */

   460     void exit(int exitCode);

   461 

   462     /**

   463      * Determines if the target VM supports watchpoints

   464      * for field modification.

   465      *

   466      * @return <code>true</code> if the feature is supported,

   467      * <code>false</code> otherwise.

   468      */

   469     boolean canWatchFieldModification();

   470 

   471     /**

   472      * Determines if the target VM supports watchpoints

   473      * for field access.

   474      *

   475      * @return <code>true</code> if the feature is supported,

   476      * <code>false</code> otherwise.

   477      */

   478     boolean canWatchFieldAccess();

   479 

   480     /**

   481      * Determines if the target VM supports the retrieval

   482      * of a method's bytecodes.

   483      *

   484      * @return <code>true</code> if the feature is supported,

   485      * <code>false</code> otherwise.

   486      */

   487     boolean canGetBytecodes();

   488 

   489     /**

   490      * Determines if the target VM supports the query

   491      * of the synthetic attribute of a method or field.

   492      *

   493      * @return <code>true</code> if the feature is supported,

   494      * <code>false</code> otherwise.

   495      */

   496     boolean canGetSyntheticAttribute();

   497 

   498     /**

   499      * Determines if the target VM supports the retrieval

   500      * of the monitors owned by a thread.

   501      *

   502      * @return <code>true</code> if the feature is supported,

   503      * <code>false</code> otherwise.

   504      */

   505     boolean canGetOwnedMonitorInfo();

   506 

   507     /**

   508      * Determines if the target VM supports the retrieval

   509      * of the monitor for which a thread is currently waiting.

   510      *

   511      * @return <code>true</code> if the feature is supported,

   512      * <code>false</code> otherwise.

   513      */

   514     boolean canGetCurrentContendedMonitor();

   515 

   516     /**

   517      * Determines if the target VM supports the retrieval

   518      * of the monitor information for an object.

   519      *

   520      * @return <code>true</code> if the feature is supported,

   521      * <code>false</code> otherwise.

   522      */

   523     boolean canGetMonitorInfo();

   524 

   525     /**

   526      * Determines if the target VM supports filtering

   527      * events by specific instance object.  For example,

   528      * see {@link com.sun.jdi.request.BreakpointRequest#addInstanceFilter}.

   529      *

   530      * @return <code>true</code> if the feature is supported,

   531      * <code>false</code> otherwise.

   532      */

   533     boolean canUseInstanceFilters();

   534 

   535     /**

   536      * Determines if the target VM supports any level

   537      * of class redefinition.

   538      * @see #redefineClasses

   539      *

   540      * @return <code>true</code> if the feature is supported,

   541      * <code>false</code> otherwise.

   542      *

   543      * @since 1.4

   544      */

   545     boolean canRedefineClasses();

   546 

   547     /**

   548      * Determines if the target VM supports the addition

   549      * of methods when performing class redefinition.

   550      * @see #redefineClasses

   551      *

   552      * @return <code>true</code> if the feature is supported,

   553      * <code>false</code> otherwise.

   554      *

   555      * @since 1.4

   556      */

   557     boolean canAddMethod();

   558 

   559     /**

   560      * Determines if the target VM supports unrestricted

   561      * changes when performing class redefinition.

   562      * @see #redefineClasses

   563      *

   564      * @return <code>true</code> if the feature is supported,

   565      * <code>false</code> otherwise.

   566      *

   567      * @since 1.4

   568      */

   569     boolean canUnrestrictedlyRedefineClasses();

   570 

   571     /**

   572      * Determines if the target VM supports popping

   573      * frames of a threads stack.

   574      * @see ThreadReference#popFrames

   575      *

   576      * @return <code>true</code> if the feature is supported,

   577      * <code>false</code> otherwise.

   578      *

   579      * @since 1.4

   580      */

   581     boolean canPopFrames();

   582 

   583     /**

   584      * Determines if the target VM supports getting

   585      * the source debug extension.

   586      * @see ReferenceType#sourceDebugExtension

   587      *

   588      * @return <code>true</code> if the feature is supported,

   589      * <code>false</code> otherwise.

   590      *

   591      * @since 1.4

   592      */

   593     boolean canGetSourceDebugExtension();

   594 

   595     /**

   596      * Determines if the target VM supports the creation of

   597      * {@link com.sun.jdi.request.VMDeathRequest}s.

   598      * @see com.sun.jdi.request.EventRequestManager#createVMDeathRequest

   599      *

   600      * @return <code>true</code> if the feature is supported,

   601      * <code>false</code> otherwise.

   602      *

   603      * @since 1.4

   604      */

   605     boolean canRequestVMDeathEvent();

   606 

   607     /**

   608      * Determines if the target VM supports the inclusion of return values

   609      * in

   610      * {@link com.sun.jdi.event.MethodExitEvent}s.

   611      * @see com.sun.jdi.request.EventRequestManager#createMethodExitRequest

   612      *

   613      * @return <code>true</code> if the feature is supported,

   614      * <code>false</code> otherwise.

   615      *

   616      * @since 1.6

   617      */

   618     boolean canGetMethodReturnValues();

   619 

   620     /**

   621      * Determines if the target VM supports the accessing of class instances,

   622      * instance counts, and referring objects.

   623      *

   624      * @see #instanceCounts

   625      * @see ReferenceType#instances(long)

   626      * @see ObjectReference#referringObjects(long)

   627      *

   628      * @return <code>true</code> if the feature is supported,

   629      * <code>false</code> otherwise.

   630      *

   631      * @since 1.6

   632      */

   633     boolean canGetInstanceInfo();

   634 

   635 

   636     /**

   637      * Determines if the target VM supports the filtering of

   638      * class prepare events by source name.

   639      *

   640      * see {@link com.sun.jdi.request.ClassPrepareRequest#addSourceNameFilter}.

   641      * @return <code>true</code> if the feature is supported,

   642      * <code>false</code> otherwise.

   643      *

   644      * @since 1.6

   645      */

   646     boolean canUseSourceNameFilters();

   647 

   648     /**

   649      * Determines if the target VM supports the forcing of a method to

   650      * return early.

   651      *

   652      * @see ThreadReference#forceEarlyReturn(Value)

   653      *

   654      * @return <code>true</code> if the feature is supported,

   655      * <code>false</code> otherwise.

   656      *

   657      * @since 1.6

   658      */

   659     boolean canForceEarlyReturn();

   660 

   661     /**

   662      * Determines if the target VM is a read-only VM.  If a method which

   663      * would modify the state of the VM is called on a read-only VM,

   664      * then {@link VMCannotBeModifiedException} is thrown.

   665      *

   666      * @return <code>true</code> if the feature is supported,

   667      * <code>false</code> otherwise.

   668      *

   669      * @since 1.5

   670      */

   671 

   672     boolean canBeModified();

   673 

   674     /**

   675      * Determines if the target VM supports the creation of

   676      * {@link com.sun.jdi.request.MonitorContendedEnterRequest}s.

   677      * {@link com.sun.jdi.request.MonitorContendedEnteredRequest}s.

   678      * {@link com.sun.jdi.request.MonitorWaitRequest}s.

   679      * {@link com.sun.jdi.request.MonitorWaitedRequest}s.

   680      * @see com.sun.jdi.request.EventRequestManager#createMonitorContendedEnterRequest

   681      * @see com.sun.jdi.request.EventRequestManager#createMonitorContendedEnteredRequest

   682      * @see com.sun.jdi.request.EventRequestManager#createMonitorWaitRequest

   683      * @see com.sun.jdi.request.EventRequestManager#createMonitorWaitedRequest

   684      *

   685      * @return <code>true</code> if the feature is supported,

   686      * <code>false</code> otherwise.

   687      *

   688      * @since 1.6

   689      */

   690 

   691     boolean canRequestMonitorEvents();

   692 

   693     /**

   694      * Determines if the target VM supports getting which

   695      * frame has acquired a monitor.

   696      * @see com.sun.jdi.ThreadReference#ownedMonitorsAndFrames

   697      *

   698      * @return <code>true</code> if the feature is supported,

   699      * <code>false</code> otherwise.

   700      *

   701      * @since 1.6

   702      */

   703 

   704      boolean canGetMonitorFrameInfo();

   705 

   706 

   707     /**

   708      * Determines if the target VM supports reading class file

   709      * major and minor versions.

   710      *

   711      * @see ReferenceType#majorVersion()

   712      * @see ReferenceType#minorVersion()

   713      *

   714      * @return <code>true</code> if the feature is supported,

   715      * <code>false</code> otherwise.

   716      *

   717      * @since 1.6

   718      */

   719     boolean canGetClassFileVersion();

   720 

   721     /**

   722      * Determines if the target VM supports getting constant pool

   723      * information of a class.

   724      *

   725      * @see ReferenceType#constantPoolCount()

   726      * @see ReferenceType#constantPool()

   727      *

   728      * @return <code>true</code> if the feature is supported,

   729      * <code>false</code> otherwise.

   730      *

   731      * @since 1.6

   732      */

   733     boolean canGetConstantPool();

   734 

   735     /**

   736      * Set this VM's default stratum (see {@link Location} for a

   737      * discussion of strata).  Overrides the per-class default set

   738      * in the class file.

   739      * <P>

   740      * Affects location queries (such as,

   741      * {@link Location#sourceName()})

   742      * and the line boundaries used in

   743      * single stepping.

   744      *

   745      * @param stratum the stratum to set as VM default,

   746      * or null to use per-class defaults.

   747      *

   748      * @throws java.lang.UnsupportedOperationException if the

   749      * target virtual machine does not support this operation.

   750      *

   751      * @since 1.4

   752      */

   753     void setDefaultStratum(String stratum);

   754 

   755     /**

   756      * Return this VM's default stratum.

   757      *

   758      * @see #setDefaultStratum(String)

   759      * @see ReferenceType#defaultStratum()

   760      * @return <code>null</code> (meaning that the per-class

   761      * default - {@link ReferenceType#defaultStratum()} -

   762      * should be used) unless the default stratum has been

   763      * set with

   764      * {@link #setDefaultStratum(String)}.

   765      *

   766      * @since 1.4

   767      */

   768     String getDefaultStratum();

   769 

   770     /**

   771      * Returns the number of instances of each ReferenceType in the 'refTypes'

   772      * list.

   773      * Only instances that are reachable for the purposes of garbage collection

   774      * are counted.

   775      * <p>

   776      * Not all target virtual machines support this operation.

   777      * Use {@link VirtualMachine#canGetInstanceInfo()}

   778      * to determine if the operation is supported.

   779      *

   780      * @see ReferenceType#instances(long)

   781      * @see ObjectReference#referringObjects(long)

   782      * @param refTypes the list of {@link ReferenceType} objects for which counts

   783      *        are to be obtained.

   784      *

   785      * @return an array of <code>long</code> containing one element for each

   786      *         element in the 'refTypes' list.  Element i of the array contains

   787      *         the number of instances in the target VM of the ReferenceType at

   788      *         position i in the 'refTypes' list.

   789      *         If the 'refTypes' list is empty, a zero-length array is returned.

   790      *         If a ReferenceType in refTypes has been garbage collected, zero

   791      *         is returned for its instance count.

   792      * @throws java.lang.UnsupportedOperationException if

   793      * the target virtual machine does not support this

   794      * operation - see

   795      * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}

   796      * @throws NullPointerException if the 'refTypes' list is null.

   797      * @since 1.6

   798      */

   799     long[] instanceCounts(List<? extends ReferenceType> refTypes);

   800 

   801     /**

   802      * Returns text information on the target VM and the

   803      * debugger support that mirrors it. No specific format

   804      * for this information is guaranteed.

   805      * Typically, this string contains version information for the

   806      * target VM and debugger interfaces.

   807      * More precise information

   808      * on VM and JDI versions is available through

   809      * {@link #version}, {@link VirtualMachineManager#majorInterfaceVersion},

   810      * and {@link VirtualMachineManager#minorInterfaceVersion}

   811      *

   812      * @return the description.

   813      */

   814     String description();

   815 

   816     /**

   817      * Returns the version of the Java Runtime Environment in the target

   818      * VM as reported by the property <code>java.version</code>.

   819      * For obtaining the JDI interface version, use

   820      * {@link VirtualMachineManager#majorInterfaceVersion}

   821      * and {@link VirtualMachineManager#minorInterfaceVersion}

   822      *

   823      * @return the target VM version.

   824      */

   825     String version();

   826 

   827     /**

   828      * Returns the name of the target VM as reported by the

   829      * property <code>java.vm.name</code>.

   830      *

   831      * @return the target VM name.

   832      */

   833     String name();

   834 

   835     /** All tracing is disabled. */

   836     int TRACE_NONE        = 0x00000000;

   837     /** Tracing enabled for JDWP packets sent to target VM. */

   838     int TRACE_SENDS       = 0x00000001;

   839     /** Tracing enabled for JDWP packets received from target VM. */

   840     int TRACE_RECEIVES    = 0x00000002;

   841     /** Tracing enabled for internal event handling. */

   842     int TRACE_EVENTS      = 0x00000004;

   843     /** Tracing enabled for internal managment of reference types. */

   844     int TRACE_REFTYPES    = 0x00000008;

   845     /** Tracing enabled for internal management of object references. */

   846     int TRACE_OBJREFS      = 0x00000010;

   847     /** All tracing is enabled. */

   848     int TRACE_ALL         = 0x00ffffff;

   849 

   850     /**

   851      * Traces the activities performed by the com.sun.jdi implementation.

   852      * All trace information is output to System.err. The given trace

   853      * flags are used to limit the output to only the information

   854      * desired. The given flags are in effect and the corresponding

   855      * trace will continue until the next call to

   856      * this method.

   857      * <p>

   858      * Output is implementation dependent and trace mode may be ignored.

   859      *

   860      * @param traceFlags identifies which kinds of tracing to enable.

   861      */

   862     void setDebugTraceMode(int traceFlags);

   863 }