2362N/A * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A Java virtual machine. 0N/A * <p> A <code>VirtualMachine</code> represents a Java virtual machine to which this 0N/A * Java virtual machine has attached. The Java virtual machine to which it is 0N/A * attached is sometimes called the <i>target virtual machine</i>, or <i>target VM</i>. 0N/A * An application (typically a tool such as a managemet console or profiler) uses a 0N/A * VirtualMachine to load an agent into the target VM. For example, a profiler tool 0N/A * written in the Java Language might attach to a running application and load its 0N/A * profiler agent to profile the running application. </p> 0N/A * <p> A VirtualMachine is obtained by invoking the {@link #attach(String) attach} method 0N/A * with an identifier that identifies the target virtual machine. The identifier is 0N/A * implementation-dependent but is typically the process identifier (or pid) in 0N/A * environments where each Java virtual machine runs in its own operating system process. 0N/A * Alternatively, a <code>VirtualMachine</code> instance is obtained by invoking the 0N/A * {@link #attach(VirtualMachineDescriptor) attach} method with a {@link 0N/A * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor} obtained 0N/A * from the list of virtual machine descriptors returned by the {@link #list list} method. 0N/A * Once a reference to a virtual machine is obtained, the {@link #loadAgent loadAgent}, 0N/A * {@link #loadAgentLibrary loadAgentLibrary}, and {@link #loadAgentPath loadAgentPath} 0N/A * methods are used to load agents into target virtual machine. The {@link 0N/A * #loadAgent loadAgent} method is used to load agents that are written in the Java 0N/A * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See 0N/A * {@link java.lang.instrument} for a detailed description on how these agents 0N/A * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and 0N/A * {@link #loadAgentPath loadAgentPath} methods are used to load agents that 0N/A * are deployed in a dynamic library and make use of the <a 0N/A * Interface</a>. </p> 0N/A * <p> In addition to loading agents a VirtualMachine provides read access to the 0N/A * {@link java.lang.System#getProperties() system properties} in the target VM. 0N/A * This can be useful in some environments where properties such as 0N/A * <code>java.home</code>, <code>os.name</code>, or <code>os.arch</code> are 0N/A * used to construct the path to agent that will be loaded into the target VM. 0N/A * <p> The following example demonstrates how VirtualMachine may be used:</p> 0N/A * // attach to target VM 0N/A * VirtualMachine vm = VirtualMachine.attach("2177"); 0N/A * // get system properties in target VM 0N/A * Properties props = vm.getSystemProperties(); 0N/A * // construct path to management agent 0N/A * String home = props.getProperty("java.home"); 0N/A * String agent = home + File.separator + "lib" + File.separator 0N/A * + "management-agent.jar"; 0N/A * // load agent into target VM 0N/A * vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000"); 0N/A * <p> In this example we attach to a Java virtual machine that is identified by 0N/A * the process identifier <code>2177</code>. The system properties from the target 0N/A * VM are then used to construct the path to a <i>management agent</i> which is then 0N/A * loaded into the target VM. Once loaded the client detaches from the target VM. </p> 0N/A * <p> A VirtualMachine is safe for use by multiple concurrent threads. </p> 0N/A private volatile int hash;
// 0 => not computed 0N/A * Initializes a new instance of this class. 0N/A * The attach provider creating this class. 0N/A * The abstract identifier that identifies the Java virtual machine. 0N/A * @throws NullPointerException 0N/A * If <code>provider</code> or <code>id</code> is <code>null</code>. 0N/A * Return a list of Java virtual machines. 0N/A * <p> This method returns a list of Java {@link 0N/A * com.sun.tools.attach.VirtualMachineDescriptor} elements. 0N/A * The list is an aggregation of the virtual machine 0N/A * descriptor lists obtained by invoking the {@link 0N/A * com.sun.tools.attach.spi.AttachProvider#listVirtualMachines 0N/A * listVirtualMachines} method of all installed 0N/A * {@link com.sun.tools.attach.spi.AttachProvider attach providers}. 0N/A * If there are no Java virtual machines known to any provider 0N/A * then an empty list is returned. 0N/A * @return The list of virtual machine descriptors. 0N/A * Attaches to a Java virtual machine. 0N/A * <p> This method obtains the list of attach providers by invoking the 0N/A * {@link com.sun.tools.attach.spi.AttachProvider#providers() 0N/A * AttachProvider.providers()} method. It then iterates overs the list 0N/A * and invokes each provider's {@link 0N/A * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(java.lang.String) 0N/A * attachVirtualMachine} method in turn. If a provider successfully 0N/A * attaches then the iteration terminates, and the VirtualMachine created 0N/A * by the provider that successfully attached is returned by this method. 0N/A * If the <code>attachVirtualMachine</code> method of all providers throws 0N/A * {@link com.sun.tools.attach.AttachNotSupportedException AttachNotSupportedException} 0N/A * then this method also throws <code>AttachNotSupportedException</code>. 0N/A * This means that <code>AttachNotSupportedException</code> is thrown when 0N/A * the identifier provided to this method is invalid, or the identifier 0N/A * corresponds to a Java virtual machine that does not exist, or none 0N/A * of the providers can attach to it. This exception is also thrown if 0N/A * {@link com.sun.tools.attach.spi.AttachProvider#providers() 0N/A * AttachProvider.providers()} returns an empty list. </p> 0N/A * The abstract identifier that identifies the Java virtual machine. 0N/A * @return A VirtualMachine representing the target VM. 0N/A * @throws SecurityException 0N/A * If a security manager has been installed and it denies 0N/A * {@link com.sun.tools.attach.AttachPermission AttachPermission} 0N/A * <tt>("attachVirtualMachine")</tt>, or another permission 0N/A * required by the implementation. 0N/A * @throws AttachNotSupportedException 0N/A * If the <code>attachVirtualmachine</code> method of all installed 0N/A * providers throws <code>AttachNotSupportedException</code>, or 0N/A * there aren't any providers installed. 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>id</code> is <code>null</code>. 0N/A * Attaches to a Java virtual machine. 0N/A * <p> This method first invokes the {@link 0N/A * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method 0N/A * of the given virtual machine descriptor to obtain the attach provider. It 0N/A * then invokes the attach provider's {@link 0N/A * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(VirtualMachineDescriptor) 0N/A * attachVirtualMachine} to attach to the target VM. 0N/A * The virtual machine descriptor. 0N/A * @return A VirtualMachine representing the target VM. 0N/A * @throws SecurityException 0N/A * If a security manager has been installed and it denies 0N/A * {@link com.sun.tools.attach.AttachPermission AttachPermission} 0N/A * <tt>("attachVirtualMachine")</tt>, or another permission 0N/A * required by the implementation. 0N/A * @throws AttachNotSupportedException 0N/A * If the attach provider's <code>attachVirtualmachine</code> 0N/A * throws <code>AttachNotSupportedException</code>. 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>vmd</code> is <code>null</code>. 0N/A * Detach from the virtual machine. 0N/A * <p> After detaching from the virtual machine, any further attempt to invoke 0N/A * operations on that virtual machine will cause an {@link java.io.IOException 0N/A * IOException} to be thrown. If an operation (such as {@link #loadAgent 0N/A * loadAgent} for example) is in progress when this method is invoked then 0N/A * the behaviour is implementation dependent. In other words, it is 0N/A * implementation specific if the operation completes or throws 0N/A * <tt>IOException</tt>. 0N/A * <p> If already detached from the virtual machine then invoking this 0N/A * method has no effect. </p> 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * Returns the provider that created this virtual machine. 0N/A * @return The provider that created this virtual machine. 0N/A * Returns the identifier for this Java virtual machine. 0N/A * @return The identifier for this Java virtual machine. 0N/A * Loads an agent library. 0N/A * TI</a> client is called an <i>agent</i>. It is developed in a native language. 0N/A * A JVM TI agent is deployed in a platform specific manner but it is typically the 0N/A * platform equivalent of a dynamic library. This method causes the given agent 0N/A * library to be loaded into the target VM (if not already loaded). 0N/A * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function 0N/A * as specified in the 0N/A * Interface</a> specification. Note that the <code>Agent_OnAttach</code> 0N/A * function is invoked even if the agent library was loaded prior to invoking 0N/A * <p> The agent library provided is the name of the agent library. It is interpreted 0N/A * in the target virtual machine in an implementation-dependent manner. Typically an 0N/A * implementation will expand the library name into an operating system specific file 0N/A * name. For example, on UNIX systems, the name <tt>foo</tt> might be expanded to 0N/A * <tt>libfoo.so</tt>, and located using the search path specified by the 0N/A * <tt>LD_LIBRARY_PATH</tt> environment variable.</p> 0N/A * <p> If the <code>Agent_OnAttach</code> function in the agent library returns 0N/A * an error then an {@link com.sun.tools.attach.AgentInitializationException} is 0N/A * thrown. The return value from the <code>Agent_OnAttach</code> can then be 0N/A * obtained by invoking the {@link 0N/A * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue} 0N/A * method on the exception. </p> 0N/A * @param agentLibrary 0N/A * The name of the agent library. 0N/A * The options to provide to the <code>Agent_OnAttach</code> 0N/A * function (can be <code>null</code>). 0N/A * @throws AgentLoadException 0N/A * If the agent library does not exist, or cannot be loaded for 0N/A * @throws AgentInitializationException 0N/A * If the <code>Agent_OnAttach</code> function returns an error 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>agentLibrary</code> is <code>null</code>. 0N/A * @see com.sun.tools.attach.AgentInitializationException#returnValue() 0N/A * Loads an agent library. 0N/A * <p> This convenience method works as if by invoking: 0N/A * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, null); 0N/A * </tt></blockquote> 0N/A * @param agentLibrary 0N/A * The name of the agent library. 0N/A * @throws AgentLoadException 0N/A * If the agent library does not exist, or cannot be loaded for 0N/A * @throws AgentInitializationException 0N/A * If the <code>Agent_OnAttach</code> function returns an error 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>agentLibrary</code> is <code>null</code>. 0N/A * Load a native agent library by full pathname. 0N/A * TI</a> client is called an <i>agent</i>. It is developed in a native language. 0N/A * A JVM TI agent is deployed in a platform specific manner but it is typically the 0N/A * platform equivalent of a dynamic library. This method causes the given agent 0N/A * library to be loaded into the target VM (if not already loaded). 0N/A * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function 0N/A * as specified in the 0N/A * Interface</a> specification. Note that the <code>Agent_OnAttach</code> 0N/A * function is invoked even if the agent library was loaded prior to invoking 0N/A * <p> The agent library provided is the absolute path from which to load the 0N/A * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name 0N/A * is not expanded in the target virtual machine. </p> 0N/A * <p> If the <code>Agent_OnAttach</code> function in the agent library returns 0N/A * an error then an {@link com.sun.tools.attach.AgentInitializationException} is 0N/A * thrown. The return value from the <code>Agent_OnAttach</code> can then be 0N/A * obtained by invoking the {@link 0N/A * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue} 0N/A * method on the exception. </p> 0N/A * The full path of the agent library. 0N/A * The options to provide to the <code>Agent_OnAttach</code> 0N/A * function (can be <code>null</code>). 0N/A * @throws AgentLoadException 0N/A * If the agent library does not exist, or cannot be loaded for 0N/A * @throws AgentInitializationException 0N/A * If the <code>Agent_OnAttach</code> function returns an error 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>agentPath</code> is <code>null</code>. 0N/A * @see com.sun.tools.attach.AgentInitializationException#returnValue() 0N/A * Load a native agent library by full pathname. 0N/A * <p> This convenience method works as if by invoking: 0N/A * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary, null); 0N/A * </tt></blockquote> 0N/A * The full path to the agent library. 0N/A * @throws AgentLoadException 0N/A * If the agent library does not exist, or cannot be loaded for 0N/A * @throws AgentInitializationException 0N/A * If the <code>Agent_OnAttach</code> function returns an error 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>agentPath</code> is <code>null</code>. 0N/A * <p> The agent provided to this method is a path name to a JAR file on the file 0N/A * system of the target virtual machine. This path is passed to the target virtual 0N/A * machine where it is interpreted. The target virtual machine attempts to start 0N/A * the agent as specified by the {@link java.lang.instrument} specification. 0N/A * That is, the specified JAR file is added to the system class path (of the target 0N/A * virtual machine), and the <code>agentmain</code> method of the agent class, specified 0N/A * by the <code>Agent-Class</code> attribute in the JAR manifest, is invoked. This 0N/A * method completes when the <code>agentmain</code> method completes. 0N/A * Path to the JAR file containing the agent. 0N/A * The options to provide to the agent's <code>agentmain</code> 0N/A * method (can be <code>null</code>). 0N/A * @throws AgentLoadException 0N/A * If the agent does not exist, or cannot be started in the manner 0N/A * specified in the {@link java.lang.instrument} specification. 0N/A * @throws AgentInitializationException 0N/A * If the <code>agentmain</code> throws an exception 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>agent</code> is <code>null</code>. 0N/A * <p> This convenience method works as if by invoking: 0N/A * {@link #loadAgent(String, String) loadAgent}(agent, null); 0N/A * </tt></blockquote> 0N/A * Path to the JAR file containing the agent. 0N/A * @throws AgentLoadException 0N/A * If the agent does not exist, or cannot be started in the manner 0N/A * specified in the {@link java.lang.instrument} specification. 0N/A * @throws AgentInitializationException 0N/A * If the <code>agentmain</code> throws an exception 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @throws NullPointerException 0N/A * If <code>agent</code> is <code>null</code>. 0N/A * Returns the current system properties in the target virtual machine. 0N/A * <p> This method returns the system properties in the target virtual 0N/A * machine. Properties whose key or value is not a <tt>String</tt> are 0N/A * omitted. The method is approximately equivalent to the invocation of the 0N/A * method {@link java.lang.System#getProperties System.getProperties} 0N/A * in the target virtual machine except that properties with a key or 0N/A * value that is not a <tt>String</tt> are not included. 0N/A * <p> This method is typically used to decide which agent to load into 0N/A * the target virtual machine with {@link #loadAgent loadAgent}, or 0N/A * {@link #loadAgentLibrary loadAgentLibrary}. For example, the 0N/A * <code>java.home</code> or <code>user.dir</code> properties might be 0N/A * use to create the path to the agent library or JAR file. 0N/A * @return The system properties 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * @see java.lang.System#getProperties 0N/A * @see #loadAgentLibrary 0N/A * Returns the current <i>agent properties</i> in the target virtual 0N/A * <p> The target virtual machine can maintain a list of properties on 0N/A * behalf of agents. The manner in which this is done, the names of the 0N/A * properties, and the types of values that are allowed, is implementation 0N/A * specific. Agent properties are typically used to store communication 0N/A * end-points and other agent configuration details. For example, a debugger 0N/A * agent might create an agent property for its transport address. 0N/A * <p> This method returns the agent properties whose key and value is a 0N/A * <tt>String</tt>. Properties whose key or value is not a <tt>String</tt> 0N/A * are omitted. If there are no agent properties maintained in the target 0N/A * virtual machine then an empty property list is returned. 0N/A * @return The agent properties 0N/A * @throws IOException 0N/A * If an I/O error occurs 0N/A * Returns a hash-code value for this VirtualMachine. The hash 0N/A * code is based upon the VirtualMachine's components, and satifies 0N/A * the general contract of the {@link java.lang.Object#hashCode() 0N/A * Object.hashCode} method. 0N/A * @return A hash-code value for this virtual machine 0N/A * Tests this VirtualMachine for equality with another object. 0N/A * <p> If the given object is not a VirtualMachine then this 0N/A * method returns <tt>false</tt>. For two VirtualMachines to 0N/A * be considered equal requires that they both reference the same 0N/A * provider, and their {@link VirtualMachineDescriptor#id() identifiers} are equal. </p> 0N/A * <p> This method satisfies the general contract of the {@link 0N/A * java.lang.Object#equals(Object) Object.equals} method. </p> 0N/A * @param ob The object to which this object is to be compared 0N/A * @return <tt>true</tt> if, and only if, the given object is 0N/A * a VirtualMachine that is equal to this 0N/A * Returns the string representation of the <code>VirtualMachine</code>.