1 /*
   2  * Copyright (c) 2005, 2006, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.tools.attach;
  27 
  28 import com.sun.tools.attach.spi.AttachProvider;
  29 import java.util.ArrayList;
  30 import java.util.List;
  31 import java.util.Properties;
  32 import java.io.IOException;
  33 
  34 
  35 /**
  36  * A Java virtual machine.
  37  *
  38  * <p> A <code>VirtualMachine</code> represents a Java virtual machine to which this
  39  * Java virtual machine has attached. The Java virtual machine to which it is
  40  * attached is sometimes called the <i>target virtual machine</i>, or <i>target VM</i>.
  41  * An application (typically a tool such as a managemet console or profiler) uses a
  42  * VirtualMachine to load an agent into the target VM. For example, a profiler tool
  43  * written in the Java Language might attach to a running application and load its
  44  * profiler agent to profile the running application. </p>
  45  *
  46  * <p> A VirtualMachine is obtained by invoking the {@link #attach(String) attach} method
  47  * with an identifier that identifies the target virtual machine. The identifier is
  48  * implementation-dependent but is typically the process identifier (or pid) in
  49  * environments where each Java virtual machine runs in its own operating system process.
  50  * Alternatively, a <code>VirtualMachine</code> instance is obtained by invoking the
  51  * {@link #attach(VirtualMachineDescriptor) attach} method with a {@link
  52  * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor} obtained
  53  * from the list of virtual machine descriptors returned by the {@link #list list} method.
  54  * Once a reference to a virtual machine is obtained, the {@link #loadAgent loadAgent},
  55  * {@link #loadAgentLibrary loadAgentLibrary}, and {@link #loadAgentPath loadAgentPath}
  56  * methods are used to load agents into target virtual machine. The {@link
  57  * #loadAgent loadAgent} method is used to load agents that are written in the Java
  58  * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See
  59  * {@link java.lang.instrument} for a detailed description on how these agents
  60  * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and
  61  * {@link #loadAgentPath loadAgentPath} methods are used to load agents that
  62  * are deployed in a dynamic library and make use of the <a
  63  * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools
  64  * Interface</a>. </p>
  65  *
  66  * <p> In addition to loading agents a VirtualMachine provides read access to the
  67  * {@link java.lang.System#getProperties() system properties} in the target VM.
  68  * This can be useful in some environments where properties such as
  69  * <code>java.home</code>, <code>os.name</code>, or <code>os.arch</code> are
  70  * used to construct the path to agent that will be loaded into the target VM.
  71  *
  72  * <p> The following example demonstrates how VirtualMachine may be used:</p>
  73  *
  74  * <pre>
  75  *
  76  *      // attach to target VM
  77  *      VirtualMachine vm = VirtualMachine.attach("2177");
  78  *
  79  *      // get system properties in target VM
  80  *      Properties props = vm.getSystemProperties();
  81  *
  82  *      // construct path to management agent
  83  *      String home = props.getProperty("java.home");
  84  *      String agent = home + File.separator + "lib" + File.separator
  85  *          + "management-agent.jar";
  86  *
  87  *      // load agent into target VM
  88  *      vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000");
  89  *
  90  *      // detach
  91  *      vm.detach();
  92  *
  93  * </pre>
  94  *
  95  * <p> In this example we attach to a Java virtual machine that is identified by
  96  * the process identifier <code>2177</code>. The system properties from the target
  97  * VM are then used to construct the path to a <i>management agent</i> which is then
  98  * loaded into the target VM. Once loaded the client detaches from the target VM. </p>
  99  *
 100  * <p> A VirtualMachine is safe for use by multiple concurrent threads. </p>
 101  *
 102  * @since 1.6
 103  */
 104 
 105 public abstract class VirtualMachine {
 106     private AttachProvider provider;
 107     private String id;
 108     private volatile int hash;        // 0 => not computed
 109 
 110     /**
 111      * Initializes a new instance of this class.
 112      *
 113      * @param   provider
 114      *          The attach provider creating this class.
 115      * @param   id
 116      *          The abstract identifier that identifies the Java virtual machine.
 117      *
 118      * @throws  NullPointerException
 119      *          If <code>provider</code> or <code>id</code> is <code>null</code>.
 120      */
 121     protected VirtualMachine(AttachProvider provider, String id) {
 122         if (provider == null) {
 123             throw new NullPointerException("provider cannot be null");
 124         }
 125         if (id == null) {
 126             throw new NullPointerException("id cannot be null");
 127         }
 128         this.provider = provider;
 129         this.id = id;
 130     }
 131 
 132     /**
 133      * Return a list of Java virtual machines.
 134      *
 135      * <p> This method returns a list of Java {@link
 136      * com.sun.tools.attach.VirtualMachineDescriptor} elements.
 137      * The list is an aggregation of the virtual machine
 138      * descriptor lists obtained by invoking the {@link
 139      * com.sun.tools.attach.spi.AttachProvider#listVirtualMachines
 140      * listVirtualMachines} method of all installed
 141      * {@link com.sun.tools.attach.spi.AttachProvider attach providers}.
 142      * If there are no Java virtual machines known to any provider
 143      * then an empty list is returned.
 144      *
 145      * @return  The list of virtual machine descriptors.
 146      */
 147     public static List<VirtualMachineDescriptor> list() {
 148         ArrayList<VirtualMachineDescriptor> l =
 149             new ArrayList<VirtualMachineDescriptor>();
 150         List<AttachProvider> providers = AttachProvider.providers();
 151         for (AttachProvider provider: providers) {
 152             l.addAll(provider.listVirtualMachines());
 153         }
 154         return l;
 155     }
 156 
 157     /**
 158      * Attaches to a Java virtual machine.
 159      *
 160      * <p> This method obtains the list of attach providers by invoking the
 161      * {@link com.sun.tools.attach.spi.AttachProvider#providers()
 162      * AttachProvider.providers()} method. It then iterates overs the list
 163      * and invokes each provider's {@link
 164      * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(java.lang.String)
 165      * attachVirtualMachine} method in turn. If a provider successfully
 166      * attaches then the iteration terminates, and the VirtualMachine created
 167      * by the provider that successfully attached is returned by this method.
 168      * If the <code>attachVirtualMachine</code> method of all providers throws
 169      * {@link com.sun.tools.attach.AttachNotSupportedException AttachNotSupportedException}
 170      * then this method also throws <code>AttachNotSupportedException</code>.
 171      * This means that <code>AttachNotSupportedException</code> is thrown when
 172      * the identifier provided to this method is invalid, or the identifier
 173      * corresponds to a Java virtual machine that does not exist, or none
 174      * of the providers can attach to it. This exception is also thrown if
 175      * {@link com.sun.tools.attach.spi.AttachProvider#providers()
 176      * AttachProvider.providers()} returns an empty list. </p>
 177      *
 178      * @param   id
 179      *          The abstract identifier that identifies the Java virtual machine.
 180      *
 181      * @return  A VirtualMachine representing the target VM.
 182      *
 183      * @throws  SecurityException
 184      *          If a security manager has been installed and it denies
 185      *          {@link com.sun.tools.attach.AttachPermission AttachPermission}
 186      *          <tt>("attachVirtualMachine")</tt>, or another permission
 187      *          required by the implementation.
 188      *
 189      * @throws  AttachNotSupportedException
 190      *          If the <code>attachVirtualmachine</code> method of all installed
 191      *          providers throws <code>AttachNotSupportedException</code>, or
 192      *          there aren't any providers installed.
 193      *
 194      * @throws  IOException
 195      *          If an I/O error occurs
 196      *
 197      * @throws  NullPointerException
 198      *          If <code>id</code> is <code>null</code>.
 199      */
 200     public static VirtualMachine attach(String id)
 201         throws AttachNotSupportedException, IOException
 202     {
 203         if (id == null) {
 204             throw new NullPointerException("id cannot be null");
 205         }
 206         List<AttachProvider> providers = AttachProvider.providers();
 207         if (providers.size() == 0) {
 208             throw new AttachNotSupportedException("no providers installed");
 209         }
 210         AttachNotSupportedException lastExc = null;
 211         for (AttachProvider provider: providers) {
 212             try {
 213                 return provider.attachVirtualMachine(id);
 214             } catch (AttachNotSupportedException x) {
 215                 lastExc = x;
 216             }
 217         }
 218         throw lastExc;
 219     }
 220 
 221     /**
 222      * Attaches to a Java virtual machine.
 223      *
 224      * <p> This method first invokes the {@link
 225      * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
 226      * of the given virtual machine descriptor to obtain the attach provider. It
 227      * then invokes the attach provider's {@link
 228      * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(VirtualMachineDescriptor)
 229      * attachVirtualMachine} to attach to the target VM.
 230      *
 231      * @param   vmd
 232      *          The virtual machine descriptor.
 233      *
 234      * @return  A VirtualMachine representing the target VM.
 235      *
 236      * @throws  SecurityException
 237      *          If a security manager has been installed and it denies
 238      *          {@link com.sun.tools.attach.AttachPermission AttachPermission}
 239      *          <tt>("attachVirtualMachine")</tt>, or another permission
 240      *          required by the implementation.
 241      *
 242      * @throws  AttachNotSupportedException
 243      *          If the attach provider's <code>attachVirtualmachine</code>
 244      *          throws <code>AttachNotSupportedException</code>.
 245      *
 246      * @throws  IOException
 247      *          If an I/O error occurs
 248      *
 249      * @throws  NullPointerException
 250      *          If <code>vmd</code> is <code>null</code>.
 251      */
 252     public static VirtualMachine attach(VirtualMachineDescriptor vmd)
 253         throws AttachNotSupportedException, IOException
 254     {
 255         return vmd.provider().attachVirtualMachine(vmd);
 256     }
 257 
 258     /**
 259      * Detach from the virtual machine.
 260      *
 261      * <p> After detaching from the virtual machine, any further attempt to invoke
 262      * operations on that virtual machine will cause an {@link java.io.IOException
 263      * IOException} to be thrown. If an operation (such as {@link #loadAgent
 264      * loadAgent} for example) is in progress when this method is invoked then
 265      * the behaviour is implementation dependent. In other words, it is
 266      * implementation specific if the operation completes or throws
 267      * <tt>IOException</tt>.
 268      *
 269      * <p> If already detached from the virtual machine then invoking this
 270      * method has no effect. </p>
 271      *
 272      * @throws  IOException
 273      *          If an I/O error occurs
 274      */
 275     public abstract void detach() throws IOException;
 276 
 277     /**
 278      * Returns the provider that created this virtual machine.
 279      *
 280      * @return  The provider that created this virtual machine.
 281      */
 282     public final AttachProvider provider() {
 283         return provider;
 284     }
 285 
 286     /**
 287      * Returns the identifier for this Java virtual machine.
 288      *
 289      * @return  The identifier for this Java virtual machine.
 290      */
 291     public final String id() {
 292         return id;
 293     }
 294 
 295     /**
 296      * Loads an agent library.
 297      *
 298      * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
 299      * TI</a> client is called an <i>agent</i>. It is developed in a native language.
 300      * A JVM TI agent is deployed in a platform specific manner but it is typically the
 301      * platform equivalent of a dynamic library. If a native agent library
 302      * called <code>agent-lib-name</code> is statically linked with the VM, then the
 303      * <code>Agent_OnAttach_agent-lib-name</code> function exported by the agent
 304      * is invoked.
 305      *
 306      * See the JVMTI Specification for more details.
 307      *
 308      * Otherwise, this method causes the given agent
 309      * library to be loaded into the target VM (if not already loaded).
 310      * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
 311      * or, for statically linked agents, the <code>Agent_OnAttach_agent-lib-name</code> function
 312      * as specified in the
 313      * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
 314      * Interface</a> specification. Note that the <code>Agent_OnAttach[_agent-lib-name]</code>
 315      * function is invoked even if the agent library was loaded prior to invoking
 316      * this method.
 317      *
 318      * <p> The agent library provided is the name of the agent library. It is interpreted
 319      * in the target virtual machine in an implementation-dependent manner. Typically an
 320      * implementation will expand the library name into an operating system specific file
 321      * name. For example, on UNIX systems, the name <tt>foo</tt> might be expanded to
 322      * <tt>libfoo.so</tt>, and located using the search path specified by the
 323      * <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
 324      *
 325      * <p> If the <code>Agent_OnAttach[_agent-lib-name]</code> function in the agent library returns
 326      * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
 327      * thrown. The return value from the <code>Agent_OnAttach[_agent-lib-name]</code> can then be
 328      * obtained by invoking the {@link
 329      * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
 330      * method on the exception. </p>
 331      *
 332      * @param   agentLibrary
 333      *          The name of the agent library.
 334      *
 335      * @param   options
 336      *          The options to provide to the <code>Agent_OnAttach[_agent-lib-name]</code>
 337      *          function (can be <code>null</code>).
 338      *
 339      * @throws  AgentLoadException
 340      *          If the agent library does not exist, the agent library is not
 341      *          statically linked with the VM, or the agent library cannot be
 342      *          loaded for another reason.
 343      *
 344      * @throws  AgentInitializationException
 345      *          If the <code>Agent_OnAttach</code> function returns an error
 346      *          or, for statically linked agents, if the 
 347      *          <code>Agent_OnAttach_agent-lib-name</code> function returns
 348      *          an error.
 349      *
 350      * @throws  IOException
 351      *          If an I/O error occurs
 352      *
 353      * @throws  NullPointerException
 354      *          If <code>agentLibrary</code> is <code>null</code>.
 355      *
 356      * @see     com.sun.tools.attach.AgentInitializationException#returnValue()
 357      */
 358     public abstract void loadAgentLibrary(String agentLibrary, String options)
 359         throws AgentLoadException, AgentInitializationException, IOException;
 360 
 361     /**
 362      * Loads an agent library.
 363      *
 364      * <p> This convenience method works as if by invoking:
 365      *
 366      * <blockquote><tt>
 367      * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary,&nbsp;null);
 368      * </tt></blockquote>
 369      *
 370      * @param   agentLibrary
 371      *          The name of the agent library.
 372      *
 373      * @throws  AgentLoadException
 374      *          If the agent library does not exist, the agent library is not
 375      *          statically linked with the VM, or the agent library cannot be
 376      *          loaded for another reason.
 377      *
 378      * @throws  AgentInitializationException
 379      *          If the <code>Agent_OnAttach</code> function returns an error
 380      *          or, for statically linked agents, if the 
 381      *          <code>Agent_OnAttach_agent-lib-name</code> function returns
 382      *          an error.
 383      *
 384      * @throws  IOException
 385      *          If an I/O error occurs
 386      *
 387      * @throws  NullPointerException
 388      *          If <code>agentLibrary</code> is <code>null</code>.
 389      */
 390     public void loadAgentLibrary(String agentLibrary)
 391         throws AgentLoadException, AgentInitializationException, IOException
 392     {
 393         loadAgentLibrary(agentLibrary, null);
 394     }
 395 
 396     /**
 397      * Load a native agent library by full pathname.
 398      *
 399      * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
 400      * TI</a> client is called an <i>agent</i>. It is developed in a native language.
 401      * A JVM TI agent is deployed in a platform specific manner but it is typically the
 402      * platform equivalent of a dynamic library. If a native agent library
 403      * called <code>agent-lib-name</code> is statically linked with the VM, then the
 404      * <code>Agent_OnAttach_agent-lib-name</code> function exported by the agent
 405      * is invoked.
 406      *
 407      * See the JVMTI Specification for more details.
 408      *
 409      * Otherwise, this method causes the given agent
 410      * library to be loaded into the target VM (if not already loaded).
 411      * It then causes the target VM to invoke the <code>Agent_OnAttach[_agent-lib-name]</code> function
 412      * as specified in the
 413      * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
 414      * Interface</a> specification. Note that the <code>Agent_OnAttach[_agent-lib-name]</code>
 415      * function is invoked even if the agent library was loaded prior to invoking
 416      * this method.
 417      *
 418      * <p> The agent library provided is the absolute path from which to load the
 419      * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
 420      * is not expanded in the target virtual machine. </p>
 421      *
 422      * <p> If the <code>Agent_OnAttach[_agent-lib-name]</code> function in the agent library returns
 423      * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
 424      * thrown. The return value from the <code>Agent_OnAttach[_agent-lib-name]</code> can then be
 425      * obtained by invoking the {@link
 426      * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
 427      * method on the exception. </p>
 428      *
 429      * @param   agentPath
 430      *          The full path of the agent library.
 431      *
 432      * @param   options
 433      *          The options to provide to the <code>Agent_OnAttach[_agent-lib-name]</code>
 434      *          function (can be <code>null</code>).
 435      *
 436      * @throws  AgentLoadException
 437      *          If the agent library does not exist, the agent library is not
 438      *          statically linked with the VM, or the agent library cannot be
 439      *          loaded for another reason.
 440      *
 441      * @throws  AgentInitializationException
 442      *          If the <code>Agent_OnAttach</code> function returns an error
 443      *          or, for statically linked agents, if the 
 444      *          <code>Agent_OnAttach_agent-lib-name</code> function returns an error 
 445      *
 446      * @throws  IOException
 447      *          If an I/O error occurs
 448      *
 449      * @throws  NullPointerException
 450      *          If <code>agentPath</code> is <code>null</code>.
 451      *
 452      * @see     com.sun.tools.attach.AgentInitializationException#returnValue()
 453      */
 454     public abstract void loadAgentPath(String agentPath, String options)
 455         throws AgentLoadException, AgentInitializationException, IOException;
 456 
 457     /**
 458      * Load a native agent library by full pathname.
 459      *
 460      * <p> This convenience method works as if by invoking:
 461      *
 462      * <blockquote><tt>
 463      * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary,&nbsp;null);
 464      * </tt></blockquote>
 465      *
 466      * @param   agentPath
 467      *          The full path to the agent library.
 468      *
 469      * @throws  AgentLoadException
 470      *          If the agent library does not exist, the agent library is not
 471      *          statically linked with the VM, or the agent library cannot be
 472      *          loaded for another reason.
 473      *
 474      * @throws  AgentInitializationException
 475      *          If the <code>Agent_OnAttach</code> function returns an error
 476      *          or, for statically linked agents, if the 
 477      *          <code>Agent_OnAttach_agent-lib-name</code> function returns
 478      *          an error.
 479      *
 480      * @throws  IOException
 481      *          If an I/O error occurs
 482      *
 483      * @throws  NullPointerException
 484      *          If <code>agentPath</code> is <code>null</code>.
 485      */
 486     public void loadAgentPath(String agentPath)
 487        throws AgentLoadException, AgentInitializationException, IOException
 488     {
 489         loadAgentPath(agentPath, null);
 490     }
 491 
 492 
 493    /**
 494      * Loads an agent.
 495      *
 496      * <p> The agent provided to this method is a path name to a JAR file on the file
 497      * system of the target virtual machine. This path is passed to the target virtual
 498      * machine where it is interpreted. The target virtual machine attempts to start
 499      * the agent as specified by the {@link java.lang.instrument} specification.
 500      * That is, the specified JAR file is added to the system class path (of the target
 501      * virtual machine), and the <code>agentmain</code> method of the agent class, specified
 502      * by the <code>Agent-Class</code> attribute in the JAR manifest, is invoked. This
 503      * method completes when the <code>agentmain</code> method completes.
 504      *
 505      * @param   agent
 506      *          Path to the JAR file containing the agent.
 507      *
 508      * @param   options
 509      *          The options to provide to the agent's <code>agentmain</code>
 510      *          method (can be <code>null</code>).
 511      *
 512      * @throws  AgentLoadException
 513      *          If the agent does not exist, or cannot be started in the manner
 514      *          specified in the {@link java.lang.instrument} specification.
 515      *
 516      * @throws  AgentInitializationException
 517      *          If the <code>agentmain</code> throws an exception
 518      *
 519      * @throws  IOException
 520      *          If an I/O error occurs
 521      *
 522      * @throws  NullPointerException
 523      *          If <code>agent</code> is <code>null</code>.
 524      */
 525     public abstract void loadAgent(String agent, String options)
 526         throws AgentLoadException, AgentInitializationException, IOException;
 527 
 528     /**
 529      * Loads an agent.
 530      *
 531      * <p> This convenience method works as if by invoking:
 532      *
 533      * <blockquote><tt>
 534      * {@link #loadAgent(String, String) loadAgent}(agent,&nbsp;null);
 535      * </tt></blockquote>
 536      *
 537      * @param   agent
 538      *          Path to the JAR file containing the agent.
 539      *
 540      * @throws  AgentLoadException
 541      *          If the agent does not exist, or cannot be started in the manner
 542      *          specified in the {@link java.lang.instrument} specification.
 543      *
 544      * @throws  AgentInitializationException
 545      *          If the <code>agentmain</code> throws an exception
 546      *
 547      * @throws  IOException
 548      *          If an I/O error occurs
 549      *
 550      * @throws  NullPointerException
 551      *          If <code>agent</code> is <code>null</code>.
 552      */
 553     public void loadAgent(String agent)
 554         throws AgentLoadException, AgentInitializationException, IOException
 555     {
 556         loadAgent(agent, null);
 557     }
 558 
 559     /**
 560      * Returns the current system properties in the target virtual machine.
 561      *
 562      * <p> This method returns the system properties in the target virtual
 563      * machine. Properties whose key or value is not a <tt>String</tt> are
 564      * omitted. The method is approximately equivalent to the invocation of the
 565      * method {@link java.lang.System#getProperties System.getProperties}
 566      * in the target virtual machine except that properties with a key or
 567      * value that is not a <tt>String</tt> are not included.
 568      *
 569      * <p> This method is typically used to decide which agent to load into
 570      * the target virtual machine with {@link #loadAgent loadAgent}, or
 571      * {@link #loadAgentLibrary loadAgentLibrary}. For example, the
 572      * <code>java.home</code> or <code>user.dir</code> properties might be
 573      * use to create the path to the agent library or JAR file.
 574      *
 575      * @return  The system properties
 576      *
 577      * @throws  IOException
 578      *          If an I/O error occurs
 579      *
 580      * @see     java.lang.System#getProperties
 581      * @see     #loadAgentLibrary
 582      * @see     #loadAgent
 583      */
 584     public abstract Properties getSystemProperties() throws IOException;
 585 
 586     /**
 587      * Returns the current <i>agent properties</i> in the target virtual
 588      * machine.
 589      *
 590      * <p> The target virtual machine can maintain a list of properties on
 591      * behalf of agents. The manner in which this is done, the names of the
 592      * properties, and the types of values that are allowed, is implementation
 593      * specific. Agent properties are typically used to store communication
 594      * end-points and other agent configuration details. For example, a debugger
 595      * agent might create an agent property for its transport address.
 596      *
 597      * <p> This method returns the agent properties whose key and value is a
 598      * <tt>String</tt>. Properties whose key or value is not a <tt>String</tt>
 599      * are omitted. If there are no agent properties maintained in the target
 600      * virtual machine then an empty property list is returned.
 601      *
 602      * @return       The agent properties
 603      *
 604      * @throws       IOException
 605      *               If an I/O error occurs
 606      */
 607     public abstract Properties getAgentProperties() throws IOException;
 608 
 609     /**
 610      * Returns a hash-code value for this VirtualMachine. The hash
 611      * code is based upon the VirtualMachine's components, and satifies
 612      * the general contract of the {@link java.lang.Object#hashCode()
 613      * Object.hashCode} method.
 614      *
 615      * @return  A hash-code value for this virtual machine
 616      */
 617     public int hashCode() {
 618         if (hash != 0) {
 619             return hash;
 620         }
 621         hash = provider.hashCode() * 127 + id.hashCode();
 622         return hash;
 623     }
 624 
 625     /**
 626      * Tests this VirtualMachine for equality with another object.
 627      *
 628      * <p> If the given object is not a VirtualMachine then this
 629      * method returns <tt>false</tt>. For two VirtualMachines to
 630      * be considered equal requires that they both reference the same
 631      * provider, and their {@link VirtualMachineDescriptor#id() identifiers} are equal. </p>
 632      *
 633      * <p> This method satisfies the general contract of the {@link
 634      * java.lang.Object#equals(Object) Object.equals} method. </p>
 635      *
 636      * @param   ob   The object to which this object is to be compared
 637      *
 638      * @return  <tt>true</tt> if, and only if, the given object is
 639      *                a VirtualMachine that is equal to this
 640      *                VirtualMachine.
 641      */
 642     public boolean equals(Object ob) {
 643         if (ob == this)
 644             return true;
 645         if (!(ob instanceof VirtualMachine))
 646             return false;
 647         VirtualMachine other = (VirtualMachine)ob;
 648         if (other.provider() != this.provider()) {
 649             return false;
 650         }
 651         if (!other.id().equals(this.id())) {
 652             return false;
 653         }
 654         return true;
 655     }
 656 
 657     /**
 658      * Returns the string representation of the <code>VirtualMachine</code>.
 659      */
 660     public String toString() {
 661         return provider.toString() + ": " + id;
 662     }
 663 }