com.sun.tools.attach.VirtualMachine Maven / Gradle / Ivy
/*
* Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package com.sun.tools.attach;
import java.io.*;
import java.util.*;
import com.sun.tools.attach.spi.*;
/**
* 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 {@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 VirtualMachine 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 JVM Tools
* Interface.
*
* 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
* 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
*/
public abstract class VirtualMachine
{
private final AttachProvider provider;
private final String id;
private volatile int hash; // 0 => not computed
/**
* 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.
*/
protected VirtualMachine(AttachProvider provider, String id)
{
this.provider = provider;
this.id = id;
}
/**
* Return a list of Java virtual machines.
*
* 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 list()
{
List l = new ArrayList();
List 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
* {@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 attachVirtualMachine method of all providers throws
* {@link com.sun.tools.attach.AttachNotSupportedException 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
* {@link com.sun.tools.attach.spi.AttachProvider#providers()
* AttachProvider.providers()} returns an empty list.
*
* @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}
* ("attachVirtualMachine"), or another permission
* required by the implementation.
* @throws IOException If an I/O error occurs
*/
public static VirtualMachine attach(String id) throws AttachNotSupportedException, IOException
{
List providers = AttachProvider.providers();
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 {@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}
* ("attachVirtualMachine"), or another permission
* required by the implementation.
*
* @throws AttachNotSupportedException
* If the attach provider's attachVirtualmachine
* throws AttachNotSupportedException.
*
* @throws IOException If an I/O error occurs
*
* @throws NullPointerException If vmd is null.
*/
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 {@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 IOException.
*
* If already detached from the virtual machine then invoking this method has no effect.
*
* @throws IOException If an I/O error occurs
*/
public abstract void detach() throws IOException;
/**
* Returns the provider that created this virtual machine.
*/
public final AttachProvider provider()
{
return provider;
}
/**
* Returns 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 {@link com.sun.tools.attach.AgentInitializationException} is
* thrown. The return value from the Agent_OnAttach can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception.
*
* @param agentLibrary The name of the agent library.
* @param 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.
* @throws AgentInitializationException If the Agent_OnAttach function returns an error
* @throws IOException If an I/O error occurs
* @throws NullPointerException If agentLibrary is null.
* @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:
*
*
* {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, null);
*
*
* @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 Agent_OnAttach function returns an error
* @throws IOException If an I/O error occurs
* @throws NullPointerException If agentLibrary is null.
*/
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 {@link #loadAgentLibrary 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 {@link com.sun.tools.attach.AgentInitializationException} is
* thrown. The return value from the Agent_OnAttach can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception.
*
* @param agentPath The full path of the agent library.
* @param 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.
* @throws AgentInitializationException If the Agent_OnAttach function returns an error
* @throws IOException If an I/O error occurs
* @throws NullPointerException If agentPath is null.
* @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:
*
*
* {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary, null);
*
*
* @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 Agent_OnAttach function returns an error
* @throws IOException If an I/O error occurs
* @throws NullPointerException If agentPath is null.
*/
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 {@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 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.
*
* @param agent Path to the JAR file containing the agent.
* @param 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 {@link java.lang.instrument} specification.
* @throws AgentInitializationException If the agentmain throws an exception
* @throws IOException If an I/O error occurs
* @throws NullPointerException If agent is null.
*/
public abstract void loadAgent(String agent, String options)
throws AgentLoadException, AgentInitializationException, IOException;
/**
* Loads an agent.
*
* This convenience method works as if by invoking:
*
*
* {@link #loadAgent(String, String) loadAgent}(agent, null);
*
*
* @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 agentmain throws an exception
* @throws IOException If an I/O error occurs
* @throws NullPointerException If agent is null.
*/
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 {@link java.lang.System#getProperties 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 {@link #loadAgent loadAgent}, or
* {@link #loadAgentLibrary loadAgentLibrary}. For example, the
* java.home or user.dir 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.
*
* @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 satisfies
* the general contract of the 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 {@link VirtualMachineDescriptor#id() identifiers} are equal.
*
* This method satisfies the general contract of the {@link
* java.lang.Object#equals(Object) Object.equals} method.
*
* @param ob The object to which this object is to be compared
* @return true 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;
return other.provider() == provider() && other.id().equals(id());
}
/**
* Returns the string representation of the VirtualMachine.
*/
public String toString()
{
return provider.toString() + ": " + id;
}
}