/*
 * Copyright (c) 2005, 2006, 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.
 */

package com.sun.tools.attach;

import com.sun.tools.attach.spi.AttachProvider;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;
import java.io.IOException;


A Java virtual machine.
 A VirtualMachine represents a Java virtual machine to which this
Java virtual machine has attached. The Java virtual machine to which it is
attached is sometimes called the target virtual machine, or target VM.
An application (typically a tool such as a managemet console or profiler) uses a
VirtualMachine to load an agent into the target VM. For example, a profiler tool
written in the Java Language might attach to a running application and load its
profiler agent to profile the running application. 
 A VirtualMachine is obtained by invoking the attach method with an identifier that identifies the target virtual machine. The identifier is implementation-dependent but is typically the process identifier (or pid) in environments where each Java virtual machine runs in its own operating system process. Alternatively, a VirtualMachine instance is obtained by invoking the attach method with a VirtualMachineDescriptor obtained from the list of virtual machine descriptors returned by the list method. Once a reference to a virtual machine is obtained, the loadAgent, loadAgentLibrary, and loadAgentPath methods are used to load agents into target virtual machine. The loadAgent method is used to load agents that are written in the Java Language and deployed in a JAR file. (See instrument for a detailed description on how these agents are loaded and started). The loadAgentLibrary and loadAgentPath methods are used to load agents that are deployed in a dynamic library and make use of the JVM Tools
Interface. 
 In addition to loading agents a VirtualMachine provides read access to the system properties in the target VM. This can be useful in some environments where properties such as java.home, os.name, or os.arch are
used to construct the path to agent that will be loaded into the target VM.
 The following example demonstrates how VirtualMachine may be used:
     // attach to target VM
     VirtualMachine vm = VirtualMachine.attach("2177");
     // get system properties in target VM
     Properties props = vm.getSystemProperties();
     // construct path to management agent
     String home = props.getProperty("java.home");
     String agent = home + File.separator + "lib" + File.separator
         + "management-agent.jar";
     // load agent into target VM
     vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000");
     // detach
     vm.detach();

 In this example we attach to a Java virtual machine that is identified by
the process identifier 2177. The system properties from the target
VM are then used to construct the path to a management agent which is then
loaded into the target VM. Once loaded the client detaches from the target VM. 
 A VirtualMachine is safe for use by multiple concurrent threads. 
Since:
1.6/**
 * A Java virtual machine.
 *
 * <p> A <code>VirtualMachine</code> represents a Java virtual machine to which this
 * Java virtual machine has attached. The Java virtual machine to which it is
 * attached is sometimes called the <i>target virtual machine</i>, or <i>target VM</i>.
 * An application (typically a tool such as a managemet console or profiler) uses a
 * VirtualMachine to load an agent into the target VM. For example, a profiler tool
 * written in the Java Language might attach to a running application and load its
 * profiler agent to profile the running application. </p>
 *
 * <p> A VirtualMachine is obtained by invoking the {@link #attach(String) attach} method
 * with an identifier that identifies the target virtual machine. The identifier is
 * implementation-dependent but is typically the process identifier (or pid) in
 * environments where each Java virtual machine runs in its own operating system process.
 * Alternatively, a <code>VirtualMachine</code> instance is obtained by invoking the
 * {@link #attach(VirtualMachineDescriptor) attach} method with a {@link
 * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor} obtained
 * from the list of virtual machine descriptors returned by the {@link #list list} method.
 * Once a reference to a virtual machine is obtained, the {@link #loadAgent loadAgent},
 * {@link #loadAgentLibrary loadAgentLibrary}, and {@link #loadAgentPath loadAgentPath}
 * methods are used to load agents into target virtual machine. The {@link
 * #loadAgent loadAgent} method is used to load agents that are written in the Java
 * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See
 * {@link java.lang.instrument} for a detailed description on how these agents
 * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and
 * {@link #loadAgentPath loadAgentPath} methods are used to load agents that
 * are deployed in a dynamic library and make use of the <a
 * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools
 * Interface</a>. </p>
 *
 * <p> In addition to loading agents a VirtualMachine provides read access to the
 * {@link java.lang.System#getProperties() system properties} in the target VM.
 * This can be useful in some environments where properties such as
 * <code>java.home</code>, <code>os.name</code>, or <code>os.arch</code> are
 * used to construct the path to agent that will be loaded into the target VM.
 *
 * <p> The following example demonstrates how VirtualMachine may be used:</p>
 *
 * <pre>
 *
 *      // attach to target VM
 *      VirtualMachine vm = VirtualMachine.attach("2177");
 *
 *      // get system properties in target VM
 *      Properties props = vm.getSystemProperties();
 *
 *      // construct path to management agent
 *      String home = props.getProperty("java.home");
 *      String agent = home + File.separator + "lib" + File.separator
 *          + "management-agent.jar";
 *
 *      // load agent into target VM
 *      vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000");
 *
 *      // detach
 *      vm.detach();
 *
 * </pre>
 *
 * <p> In this example we attach to a Java virtual machine that is identified by
 * the process identifier <code>2177</code>. The system properties from the target
 * VM are then used to construct the path to a <i>management agent</i> which is then
 * loaded into the target VM. Once loaded the client detaches from the target VM. </p>
 *
 * <p> A VirtualMachine is safe for use by multiple concurrent threads. </p>
 *
 * @since 1.6
 */

public abstract class VirtualMachine {
    private AttachProvider provider;
    private String id;
    private volatile int hash;        // 0 => not computed

    
Initializes a new instance of this class.
Params:
provider – 
         The attach provider creating this class.
id – 
         The abstract identifier that identifies the Java virtual machine.
Throws:
NullPointerException – 
         If provider or id is null./**
     * Initializes a new instance of this class.
     *
     * @param   provider
     *          The attach provider creating this class.
     * @param   id
     *          The abstract identifier that identifies the Java virtual machine.
     *
     * @throws  NullPointerException
     *          If <code>provider</code> or <code>id</code> is <code>null</code>.
     */
    protected VirtualMachine(AttachProvider provider, String id) {
        if (provider == null) {
            throw new NullPointerException("provider cannot be null");
        }
        if (id == null) {
            throw new NullPointerException("id cannot be null");
        }
        this.provider = provider;
        this.id = id;
    }

    
Return a list of Java virtual machines.
 This method returns a list of Java VirtualMachineDescriptor elements. The list is an aggregation of the virtual machine descriptor lists obtained by invoking the 
listVirtualMachines method of all installed attach providers. If there are no Java virtual machines known to any provider then an empty list is returned. 
Returns:
 The list of virtual machine descriptors./**
     * Return a list of Java virtual machines.
     *
     * <p> This method returns a list of Java {@link
     * com.sun.tools.attach.VirtualMachineDescriptor} elements.
     * The list is an aggregation of the virtual machine
     * descriptor lists obtained by invoking the {@link
     * com.sun.tools.attach.spi.AttachProvider#listVirtualMachines
     * listVirtualMachines} method of all installed
     * {@link com.sun.tools.attach.spi.AttachProvider attach providers}.
     * If there are no Java virtual machines known to any provider
     * then an empty list is returned.
     *
     * @return  The list of virtual machine descriptors.
     */
    public static List<VirtualMachineDescriptor> list() {
        ArrayList<VirtualMachineDescriptor> l =
            new ArrayList<VirtualMachineDescriptor>();
        List<AttachProvider> providers = AttachProvider.providers();
        for (AttachProvider provider: providers) {
            l.addAll(provider.listVirtualMachines());
        }
        return l;
    }

    
Attaches to a Java virtual machine.
 This method obtains the list of attach providers by invoking the 
AttachProvider.providers() method. It then iterates overs the list and invokes each provider's 
attachVirtualMachine method in turn. If a provider successfully attaches then the iteration terminates, and the VirtualMachine created by the provider that successfully attached is returned by this method. If the attachVirtualMachine method of all providers throws AttachNotSupportedException then this method also throws AttachNotSupportedException.
This means that AttachNotSupportedException is thrown when the identifier provided to this method is invalid, or the identifier corresponds to a Java virtual machine that does not exist, or none of the providers can attach to it. This exception is also thrown if 
AttachProvider.providers() returns an empty list. 
Params:
id – 
         The abstract identifier that identifies the Java virtual machine.
Throws:
SecurityException –  If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or another permission
         required by the implementation.
AttachNotSupportedException – 
         If the attachVirtualmachine method of all installed
         providers throws AttachNotSupportedException, or
         there aren't any providers installed.
IOException – 
         If an I/O error occurs
NullPointerException – 
         If id is null.
Returns:
 A VirtualMachine representing the target VM./**
     * Attaches to a Java virtual machine.
     *
     * <p> This method obtains the list of attach providers by invoking the
     * {@link com.sun.tools.attach.spi.AttachProvider#providers()
     * AttachProvider.providers()} method. It then iterates overs the list
     * and invokes each provider's {@link
     * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(java.lang.String)
     * attachVirtualMachine} method in turn. If a provider successfully
     * attaches then the iteration terminates, and the VirtualMachine created
     * by the provider that successfully attached is returned by this method.
     * If the <code>attachVirtualMachine</code> method of all providers throws
     * {@link com.sun.tools.attach.AttachNotSupportedException AttachNotSupportedException}
     * then this method also throws <code>AttachNotSupportedException</code>.
     * This means that <code>AttachNotSupportedException</code> is thrown when
     * the identifier provided to this method is invalid, or the identifier
     * corresponds to a Java virtual machine that does not exist, or none
     * of the providers can attach to it. This exception is also thrown if
     * {@link com.sun.tools.attach.spi.AttachProvider#providers()
     * AttachProvider.providers()} returns an empty list. </p>
     *
     * @param   id
     *          The abstract identifier that identifies the Java virtual machine.
     *
     * @return  A VirtualMachine representing the target VM.
     *
     * @throws  SecurityException
     *          If a security manager has been installed and it denies
     *          {@link com.sun.tools.attach.AttachPermission AttachPermission}
     *          <tt>("attachVirtualMachine")</tt>, or another permission
     *          required by the implementation.
     *
     * @throws  AttachNotSupportedException
     *          If the <code>attachVirtualmachine</code> method of all installed
     *          providers throws <code>AttachNotSupportedException</code>, or
     *          there aren't any providers installed.
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>id</code> is <code>null</code>.
     */
    public static VirtualMachine attach(String id)
        throws AttachNotSupportedException, IOException
    {
        if (id == null) {
            throw new NullPointerException("id cannot be null");
        }
        List<AttachProvider> providers = AttachProvider.providers();
        if (providers.size() == 0) {
            throw new AttachNotSupportedException("no providers installed");
        }
        AttachNotSupportedException lastExc = null;
        for (AttachProvider provider: providers) {
            try {
                return provider.attachVirtualMachine(id);
            } catch (AttachNotSupportedException x) {
                lastExc = x;
            }
        }
        throw lastExc;
    }

    
Attaches to a Java virtual machine.
 This method first invokes the provider() method of the given virtual machine descriptor to obtain the attach provider. It then invokes the attach provider's 
attachVirtualMachine to attach to the target VM. 
Params:
vmd – 
         The virtual machine descriptor.
Throws:
SecurityException –  If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or another permission
         required by the implementation.
AttachNotSupportedException – 
         If the attach provider's attachVirtualmachine
         throws AttachNotSupportedException.
IOException – 
         If an I/O error occurs
NullPointerException – 
         If vmd is null.
Returns:
 A VirtualMachine representing the target VM./**
     * Attaches to a Java virtual machine.
     *
     * <p> This method first invokes the {@link
     * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
     * of the given virtual machine descriptor to obtain the attach provider. It
     * then invokes the attach provider's {@link
     * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(VirtualMachineDescriptor)
     * attachVirtualMachine} to attach to the target VM.
     *
     * @param   vmd
     *          The virtual machine descriptor.
     *
     * @return  A VirtualMachine representing the target VM.
     *
     * @throws  SecurityException
     *          If a security manager has been installed and it denies
     *          {@link com.sun.tools.attach.AttachPermission AttachPermission}
     *          <tt>("attachVirtualMachine")</tt>, or another permission
     *          required by the implementation.
     *
     * @throws  AttachNotSupportedException
     *          If the attach provider's <code>attachVirtualmachine</code>
     *          throws <code>AttachNotSupportedException</code>.
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>vmd</code> is <code>null</code>.
     */
    public static VirtualMachine attach(VirtualMachineDescriptor vmd)
        throws AttachNotSupportedException, IOException
    {
        return vmd.provider().attachVirtualMachine(vmd);
    }

    
Detach from the virtual machine.
 After detaching from the virtual machine, any further attempt to invoke operations on that virtual machine will cause an 
IOException to be thrown. If an operation (such as 
loadAgent for example) is in progress when this method is invoked then the behaviour is implementation dependent. In other words, it is implementation specific if the operation completes or throws IOException.
 If already detached from the virtual machine then invoking this
method has no effect. 
Throws:
IOException – 
         If an I/O error occurs/**
     * Detach from the virtual machine.
     *
     * <p> After detaching from the virtual machine, any further attempt to invoke
     * operations on that virtual machine will cause an {@link java.io.IOException
     * IOException} to be thrown. If an operation (such as {@link #loadAgent
     * loadAgent} for example) is in progress when this method is invoked then
     * the behaviour is implementation dependent. In other words, it is
     * implementation specific if the operation completes or throws
     * <tt>IOException</tt>.
     *
     * <p> If already detached from the virtual machine then invoking this
     * method has no effect. </p>
     *
     * @throws  IOException
     *          If an I/O error occurs
     */
    public abstract void detach() throws IOException;

    
Returns the provider that created this virtual machine.
Returns:
 The provider that created this virtual machine./**
     * Returns the provider that created this virtual machine.
     *
     * @return  The provider that created this virtual machine.
     */
    public final AttachProvider provider() {
        return provider;
    }

    
Returns the identifier for this Java virtual machine.
Returns:
 The identifier for this Java virtual machine./**
     * Returns the identifier for this Java virtual machine.
     *
     * @return  The identifier for this Java virtual machine.
     */
    public final String id() {
        return id;
    }

    
Loads an agent library.
 A JVM
TI client is called an agent. It is developed in a native language.
A JVM TI agent is deployed in a platform specific manner but it is typically the
platform equivalent of a dynamic library. This method causes the given agent
library to be loaded into the target VM (if not already loaded).
It then causes the target VM to invoke the Agent_OnAttach function
as specified in the
 JVM Tools
Interface specification. Note that the Agent_OnAttach
function is invoked even if the agent library was loaded prior to invoking
this method.
 The agent library provided is the name of the agent library. It is interpreted
in the target virtual machine in an implementation-dependent manner. Typically an
implementation will expand the library name into an operating system specific file
name. For example, on UNIX systems, the name foo might be expanded to
libfoo.so, and located using the search path specified by the
LD_LIBRARY_PATH environment variable.
 If the Agent_OnAttach function in the agent library returns an error then an AgentInitializationException is thrown. The return value from the Agent_OnAttach can then be obtained by invoking the returnValue method on the exception. 
Params:
agentLibrary – 
         The name of the agent library.
options – 
         The options to provide to the Agent_OnAttach
         function (can be null).
Throws:
AgentLoadException – 
         If the agent library does not exist, or cannot be loaded for
         another reason.
AgentInitializationException – 
         If the Agent_OnAttach function returns an error
IOException – 
         If an I/O error occurs
NullPointerException – 
         If agentLibrary is null.
See Also:
AgentInitializationException.returnValue()/**
     * Loads an agent library.
     *
     * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
     * TI</a> client is called an <i>agent</i>. It is developed in a native language.
     * A JVM TI agent is deployed in a platform specific manner but it is typically the
     * platform equivalent of a dynamic library. This method causes the given agent
     * library to be loaded into the target VM (if not already loaded).
     * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
     * as specified in the
     * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
     * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
     * function is invoked even if the agent library was loaded prior to invoking
     * this method.
     *
     * <p> The agent library provided is the name of the agent library. It is interpreted
     * in the target virtual machine in an implementation-dependent manner. Typically an
     * implementation will expand the library name into an operating system specific file
     * name. For example, on UNIX systems, the name <tt>foo</tt> might be expanded to
     * <tt>libfoo.so</tt>, and located using the search path specified by the
     * <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
     *
     * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
     * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
     * thrown. The return value from the <code>Agent_OnAttach</code> can then be
     * obtained by invoking the {@link
     * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
     * method on the exception. </p>
     *
     * @param   agentLibrary
     *          The name of the agent library.
     *
     * @param   options
     *          The options to provide to the <code>Agent_OnAttach</code>
     *          function (can be <code>null</code>).
     *
     * @throws  AgentLoadException
     *          If the agent library does not exist, or cannot be loaded for
     *          another reason.
     *
     * @throws  AgentInitializationException
     *          If the <code>Agent_OnAttach</code> function returns an error
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>agentLibrary</code> is <code>null</code>.
     *
     * @see     com.sun.tools.attach.AgentInitializationException#returnValue()
     */
    public abstract void loadAgentLibrary(String agentLibrary, String options)
        throws AgentLoadException, AgentInitializationException, IOException;

    
Loads an agent library.
 This convenience method works as if by invoking:
 loadAgentLibrary(agentLibrary, null); 
Params:
agentLibrary – 
         The name of the agent library.
Throws:
AgentLoadException – 
         If the agent library does not exist, or cannot be loaded for
         another reason.
AgentInitializationException – 
         If the Agent_OnAttach function returns an error
IOException – 
         If an I/O error occurs
NullPointerException – 
         If agentLibrary is null./**
     * Loads an agent library.
     *
     * <p> This convenience method works as if by invoking:
     *
     * <blockquote><tt>
     * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary,&nbsp;null);
     * </tt></blockquote>
     *
     * @param   agentLibrary
     *          The name of the agent library.
     *
     * @throws  AgentLoadException
     *          If the agent library does not exist, or cannot be loaded for
     *          another reason.
     *
     * @throws  AgentInitializationException
     *          If the <code>Agent_OnAttach</code> function returns an error
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>agentLibrary</code> is <code>null</code>.
     */
    public void loadAgentLibrary(String agentLibrary)
        throws AgentLoadException, AgentInitializationException, IOException
    {
        loadAgentLibrary(agentLibrary, null);
    }

    
Load a native agent library by full pathname.
 A JVM
TI client is called an agent. It is developed in a native language.
A JVM TI agent is deployed in a platform specific manner but it is typically the
platform equivalent of a dynamic library. This method causes the given agent
library to be loaded into the target VM (if not already loaded).
It then causes the target VM to invoke the Agent_OnAttach function
as specified in the
 JVM Tools
Interface specification. Note that the Agent_OnAttach
function is invoked even if the agent library was loaded prior to invoking
this method.
 The agent library provided is the absolute path from which to load the agent library. Unlike loadAgentLibrary, the library name is not expanded in the target virtual machine. 
 If the Agent_OnAttach function in the agent library returns an error then an AgentInitializationException is thrown. The return value from the Agent_OnAttach can then be obtained by invoking the returnValue method on the exception. 
Params:
agentPath – 
         The full path of the agent library.
options – 
         The options to provide to the Agent_OnAttach
         function (can be null).
Throws:
AgentLoadException – 
         If the agent library does not exist, or cannot be loaded for
         another reason.
AgentInitializationException – 
         If the Agent_OnAttach function returns an error
IOException – 
         If an I/O error occurs
NullPointerException – 
         If agentPath is null.
See Also:
AgentInitializationException.returnValue()/**
     * Load a native agent library by full pathname.
     *
     * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
     * TI</a> client is called an <i>agent</i>. It is developed in a native language.
     * A JVM TI agent is deployed in a platform specific manner but it is typically the
     * platform equivalent of a dynamic library. This method causes the given agent
     * library to be loaded into the target VM (if not already loaded).
     * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
     * as specified in the
     * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
     * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
     * function is invoked even if the agent library was loaded prior to invoking
     * this method.
     *
     * <p> The agent library provided is the absolute path from which to load the
     * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
     * is not expanded in the target virtual machine. </p>
     *
     * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
     * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
     * thrown. The return value from the <code>Agent_OnAttach</code> can then be
     * obtained by invoking the {@link
     * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
     * method on the exception. </p>
     *
     * @param   agentPath
     *          The full path of the agent library.
     *
     * @param   options
     *          The options to provide to the <code>Agent_OnAttach</code>
     *          function (can be <code>null</code>).
     *
     * @throws  AgentLoadException
     *          If the agent library does not exist, or cannot be loaded for
     *          another reason.
     *
     * @throws  AgentInitializationException
     *          If the <code>Agent_OnAttach</code> function returns an error
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>agentPath</code> is <code>null</code>.
     *
     * @see     com.sun.tools.attach.AgentInitializationException#returnValue()
     */
    public abstract void loadAgentPath(String agentPath, String options)
        throws AgentLoadException, AgentInitializationException, IOException;

    
Load a native agent library by full pathname.
 This convenience method works as if by invoking:
 loadAgentPath(agentLibrary, null); 
Params:
agentPath – 
         The full path to the agent library.
Throws:
AgentLoadException – 
         If the agent library does not exist, or cannot be loaded for
         another reason.
AgentInitializationException – 
         If the Agent_OnAttach function returns an error
IOException – 
         If an I/O error occurs
NullPointerException – 
         If agentPath is null./**
     * Load a native agent library by full pathname.
     *
     * <p> This convenience method works as if by invoking:
     *
     * <blockquote><tt>
     * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary,&nbsp;null);
     * </tt></blockquote>
     *
     * @param   agentPath
     *          The full path to the agent library.
     *
     * @throws  AgentLoadException
     *          If the agent library does not exist, or cannot be loaded for
     *          another reason.
     *
     * @throws  AgentInitializationException
     *          If the <code>Agent_OnAttach</code> function returns an error
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>agentPath</code> is <code>null</code>.
     */
    public void loadAgentPath(String agentPath)
       throws AgentLoadException, AgentInitializationException, IOException
    {
        loadAgentPath(agentPath, null);
    }


   
Loads an agent.
 The agent provided to this method is a path name to a JAR file on the file system of the target virtual machine. This path is passed to the target virtual machine where it is interpreted. The target virtual machine attempts to start the agent as specified by the instrument specification. That is, the specified JAR file is added to the system class path (of the target virtual machine), and the agentmain method of the agent class, specified
by the Agent-Class attribute in the JAR manifest, is invoked. This
method completes when the agentmain method completes.
Params:
agent – 
         Path to the JAR file containing the agent.
options – 
         The options to provide to the agent's agentmain
         method (can be null).
Throws:
AgentLoadException –  If the agent does not exist, or cannot be started in the manner specified in the instrument specification.
AgentInitializationException – 
         If the agentmain throws an exception
IOException – 
         If an I/O error occurs
NullPointerException – 
         If agent is null./**
     * Loads an agent.
     *
     * <p> The agent provided to this method is a path name to a JAR file on the file
     * system of the target virtual machine. This path is passed to the target virtual
     * machine where it is interpreted. The target virtual machine attempts to start
     * the agent as specified by the {@link java.lang.instrument} specification.
     * That is, the specified JAR file is added to the system class path (of the target
     * virtual machine), and the <code>agentmain</code> method of the agent class, specified
     * by the <code>Agent-Class</code> attribute in the JAR manifest, is invoked. This
     * method completes when the <code>agentmain</code> method completes.
     *
     * @param   agent
     *          Path to the JAR file containing the agent.
     *
     * @param   options
     *          The options to provide to the agent's <code>agentmain</code>
     *          method (can be <code>null</code>).
     *
     * @throws  AgentLoadException
     *          If the agent does not exist, or cannot be started in the manner
     *          specified in the {@link java.lang.instrument} specification.
     *
     * @throws  AgentInitializationException
     *          If the <code>agentmain</code> throws an exception
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>agent</code> is <code>null</code>.
     */
    public abstract void loadAgent(String agent, String options)
        throws AgentLoadException, AgentInitializationException, IOException;

    
Loads an agent.
 This convenience method works as if by invoking:
 loadAgent(agent, null); 
Params:
agent – 
         Path to the JAR file containing the agent.
Throws:
AgentLoadException –  If the agent does not exist, or cannot be started in the manner specified in the instrument specification.
AgentInitializationException – 
         If the agentmain throws an exception
IOException – 
         If an I/O error occurs
NullPointerException – 
         If agent is null./**
     * Loads an agent.
     *
     * <p> This convenience method works as if by invoking:
     *
     * <blockquote><tt>
     * {@link #loadAgent(String, String) loadAgent}(agent,&nbsp;null);
     * </tt></blockquote>
     *
     * @param   agent
     *          Path to the JAR file containing the agent.
     *
     * @throws  AgentLoadException
     *          If the agent does not exist, or cannot be started in the manner
     *          specified in the {@link java.lang.instrument} specification.
     *
     * @throws  AgentInitializationException
     *          If the <code>agentmain</code> throws an exception
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @throws  NullPointerException
     *          If <code>agent</code> is <code>null</code>.
     */
    public void loadAgent(String agent)
        throws AgentLoadException, AgentInitializationException, IOException
    {
        loadAgent(agent, null);
    }

    
Returns the current system properties in the target virtual machine.
 This method returns the system properties in the target virtual
machine. Properties whose key or value is not a String are omitted. The method is approximately equivalent to the invocation of the method System.getProperties in the target virtual machine except that properties with a key or value that is not a String are not included.
 This method is typically used to decide which agent to load into the target virtual machine with loadAgent, or loadAgentLibrary. For example, the java.home or user.dir properties might be
use to create the path to the agent library or JAR file.
Throws:
IOException – 
         If an I/O error occurs
See Also:
System.getProperties
loadAgentLibrary
loadAgent
Returns:
 The system properties/**
     * Returns the current system properties in the target virtual machine.
     *
     * <p> This method returns the system properties in the target virtual
     * machine. Properties whose key or value is not a <tt>String</tt> are
     * omitted. The method is approximately equivalent to the invocation of the
     * method {@link java.lang.System#getProperties System.getProperties}
     * in the target virtual machine except that properties with a key or
     * value that is not a <tt>String</tt> are not included.
     *
     * <p> This method is typically used to decide which agent to load into
     * the target virtual machine with {@link #loadAgent loadAgent}, or
     * {@link #loadAgentLibrary loadAgentLibrary}. For example, the
     * <code>java.home</code> or <code>user.dir</code> properties might be
     * use to create the path to the agent library or JAR file.
     *
     * @return  The system properties
     *
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @see     java.lang.System#getProperties
     * @see     #loadAgentLibrary
     * @see     #loadAgent
     */
    public abstract Properties getSystemProperties() throws IOException;

    
Returns the current agent properties in the target virtual
machine.
 The target virtual machine can maintain a list of properties on
behalf of agents. The manner in which this is done, the names of the
properties, and the types of values that are allowed, is implementation
specific. Agent properties are typically used to store communication
end-points and other agent configuration details. For example, a debugger
agent might create an agent property for its transport address.
 This method returns the agent properties whose key and value is a
String. Properties whose key or value is not a String
are omitted. If there are no agent properties maintained in the target
virtual machine then an empty property list is returned.
Throws:
IOException – 
              If an I/O error occurs
Returns:
      The agent properties/**
     * Returns the current <i>agent properties</i> in the target virtual
     * machine.
     *
     * <p> The target virtual machine can maintain a list of properties on
     * behalf of agents. The manner in which this is done, the names of the
     * properties, and the types of values that are allowed, is implementation
     * specific. Agent properties are typically used to store communication
     * end-points and other agent configuration details. For example, a debugger
     * agent might create an agent property for its transport address.
     *
     * <p> This method returns the agent properties whose key and value is a
     * <tt>String</tt>. Properties whose key or value is not a <tt>String</tt>
     * are omitted. If there are no agent properties maintained in the target
     * virtual machine then an empty property list is returned.
     *
     * @return       The agent properties
     *
     * @throws       IOException
     *               If an I/O error occurs
     */
    public abstract Properties getAgentProperties() throws IOException;

    
Returns a hash-code value for this VirtualMachine. The hash code is based upon the VirtualMachine's components, and satifies the general contract of the 
Object.hashCode method. 
Returns:
 A hash-code value for this virtual machine/**
     * Returns a hash-code value for this VirtualMachine. The hash
     * code is based upon the VirtualMachine's components, and satifies
     * the general contract of the {@link java.lang.Object#hashCode()
     * Object.hashCode} method.
     *
     * @return  A hash-code value for this virtual machine
     */
    public int hashCode() {
        if (hash != 0) {
            return hash;
        }
        hash = provider.hashCode() * 127 + id.hashCode();
        return hash;
    }

    
Tests this VirtualMachine for equality with another object.
 If the given object is not a VirtualMachine then this
method returns false. For two VirtualMachines to be considered equal requires that they both reference the same provider, and their identifiers are equal. 
 This method satisfies the general contract of the Object.equals method. 
Params:
ob –   The object to which this object is to be compared
Returns:
 true if, and only if, the given object is
               a VirtualMachine that is equal to this
               VirtualMachine./**
     * Tests this VirtualMachine for equality with another object.
     *
     * <p> If the given object is not a VirtualMachine then this
     * method returns <tt>false</tt>. For two VirtualMachines to
     * be considered equal requires that they both reference the same
     * provider, and their {@link VirtualMachineDescriptor#id() identifiers} are equal. </p>
     *
     * <p> This method satisfies the general contract of the {@link
     * java.lang.Object#equals(Object) Object.equals} method. </p>
     *
     * @param   ob   The object to which this object is to be compared
     *
     * @return  <tt>true</tt> if, and only if, the given object is
     *                a VirtualMachine that is equal to this
     *                VirtualMachine.
     */
    public boolean equals(Object ob) {
        if (ob == this)
            return true;
        if (!(ob instanceof VirtualMachine))
            return false;
        VirtualMachine other = (VirtualMachine)ob;
        if (other.provider() != this.provider()) {
            return false;
        }
        if (!other.id().equals(this.id())) {
            return false;
        }
        return true;
    }

    
Returns the string representation of the VirtualMachine.
/**
     * Returns the string representation of the <code>VirtualMachine</code>.
     */
    public String toString() {
        return provider.toString() + ": " + id;
    }
}