diff options
Diffstat (limited to 'kamon-autoweave/src/main/java/com')
6 files changed, 1176 insertions, 0 deletions
diff --git a/kamon-autoweave/src/main/java/com/sun/tools/attach/AgentInitializationException.java b/kamon-autoweave/src/main/java/com/sun/tools/attach/AgentInitializationException.java new file mode 100644 index 00000000..c31ab371 --- /dev/null +++ b/kamon-autoweave/src/main/java/com/sun/tools/attach/AgentInitializationException.java @@ -0,0 +1,90 @@ +/* + * 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; + +/** + * The exception thrown when an agent fails to initialize in the target Java virtual machine. + * <p/> + * <p> This exception is thrown by {@link + * VirtualMachine#loadAgent VirtualMachine.loadAgent}, + * {@link VirtualMachine#loadAgentLibrary + * VirtualMachine.loadAgentLibrary}, {@link + * VirtualMachine#loadAgentPath VirtualMachine.loadAgentPath} + * methods if an agent, or agent library, cannot be initialized. + * When thrown by <tt>VirtualMachine.loadAgentLibrary</tt>, or + * <tt>VirtualMachine.loadAgentPath</tt> then the exception encapsulates + * the error returned by the agent's <code>Agent_OnAttach</code> function. + * This error code can be obtained by invoking the {@link #returnValue() returnValue} method. + */ +public final class AgentInitializationException extends Exception +{ + private static final long serialVersionUID = -1508756333332806353L; + + private final int returnValue; + + /** + * Constructs an <code>AgentInitializationException</code> with + * no detail message. + */ + public AgentInitializationException() + { + returnValue = 0; + } + + /** + * Constructs an <code>AgentInitializationException</code> with the specified detail message. + * + * @param s the detail message. + */ + public AgentInitializationException(String s) + { + super(s); + returnValue = 0; + } + + /** + * Constructs an <code>AgentInitializationException</code> with + * the specified detail message and the return value from the + * execution of the agent's <code>Agent_OnAttach</code> function. + * + * @param s the detail message. + * @param returnValue the return value + */ + public AgentInitializationException(String s, int returnValue) + { + super(s); + this.returnValue = returnValue; + } + + /** + * If the exception was created with the return value from the agent + * <code>Agent_OnAttach</code> function then this returns that value, + * otherwise returns <code>0</code>. </p> + */ + public int returnValue() + { + return returnValue; + } +} diff --git a/kamon-autoweave/src/main/java/com/sun/tools/attach/AgentLoadException.java b/kamon-autoweave/src/main/java/com/sun/tools/attach/AgentLoadException.java new file mode 100644 index 00000000..816255a5 --- /dev/null +++ b/kamon-autoweave/src/main/java/com/sun/tools/attach/AgentLoadException.java @@ -0,0 +1,55 @@ +/* + * Copyright 2005 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; + +/** + * The exception thrown when an agent cannot be loaded into the target Java virtual machine. + * <p/> + * <p> This exception is thrown by {@link + * VirtualMachine#loadAgent VirtualMachine.loadAgent} or + * {@link VirtualMachine#loadAgentLibrary + * VirtualMachine.loadAgentLibrary}, {@link VirtualMachine#loadAgentPath loadAgentPath} methods + * if the agent, or agent library, cannot be loaded. + */ +public final class AgentLoadException extends Exception +{ + private static final long serialVersionUID = 688047862952114238L; + + /** + * Constructs an <code>AgentLoadException</code> with + * no detail message. + */ + public AgentLoadException() + { + } + + /** + * Constructs an <code>AgentLoadException</code> with the specified detail message. + */ + public AgentLoadException(String s) + { + super(s); + } +} diff --git a/kamon-autoweave/src/main/java/com/sun/tools/attach/AttachNotSupportedException.java b/kamon-autoweave/src/main/java/com/sun/tools/attach/AttachNotSupportedException.java new file mode 100644 index 00000000..7b59e6e2 --- /dev/null +++ b/kamon-autoweave/src/main/java/com/sun/tools/attach/AttachNotSupportedException.java @@ -0,0 +1,56 @@ +/* + * Copyright 2005 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; + +/** + * Thrown by {@link VirtualMachine#attach VirtalMachine.attach} when attempting to attach to a Java + * virtual machine for which a compatible {@link com.sun.tools.attach.spi.AttachProvider + * AttachProvider} does not exist. It is also thrown by {@link + * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine + * AttachProvider.attachVirtualMachine} if the provider attempts to + * attach to a Java virtual machine with which it not compatible. + */ +public final class AttachNotSupportedException extends Exception +{ + private static final long serialVersionUID = 3391824968260177264L; + + /** + * Constructs an <code>AttachNotSupportedException</code> with no detail message. + */ + public AttachNotSupportedException() + { + } + + /** + * Constructs an <code>AttachNotSupportedException</code> with + * the specified detail message. + * + * @param s the detail message. + */ + public AttachNotSupportedException(String s) + { + super(s); + } +} diff --git a/kamon-autoweave/src/main/java/com/sun/tools/attach/VirtualMachine.java b/kamon-autoweave/src/main/java/com/sun/tools/attach/VirtualMachine.java new file mode 100644 index 00000000..e1f010f8 --- /dev/null +++ b/kamon-autoweave/src/main/java/com/sun/tools/attach/VirtualMachine.java @@ -0,0 +1,527 @@ +/* + * 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 com.sun.tools.attach.spi.AttachProvider; + +import java.io.IOException; +import java.util.ArrayList; +import java.util.List; +import java.util.Properties; + +/** + * A Java virtual machine. + * <p/> + * <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/> + * <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/> + * <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/> + * <p> The following example demonstrates how VirtualMachine may be used:</p> + * <p/> + * <pre> + * <p/> + * // attach to target VM + * VirtualMachine vm = VirtualMachine.attach("2177"); + * <p/> + * // get system properties in target VM + * Properties props = vm.getSystemProperties(); + * <p/> + * // construct path to management agent + * String home = props.getProperty("java.home"); + * String agent = home + File.separator + "lib" + File.separator + * + "management-agent.jar"; + * <p/> + * // load agent into target VM + * vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000"); + * <p/> + * // detach + * vm.detach(); + * <p/> + * </pre> + * <p/> + * <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/> + * <p> A VirtualMachine is safe for use by multiple concurrent threads. </p> + * + * @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. + * <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() + { + List<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. + * <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 IOException If an I/O error occurs + */ + public static VirtualMachine attach(String id) throws AttachNotSupportedException, IOException + { + List<AttachProvider> 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. + * <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. + * <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. + * + * @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. + * <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/> + * 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. + * + * @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. + * <p/> + * This convenience method works as if by invoking: + * <p/> + * <blockquote><tt> + * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, 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. + * <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/> + * 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. + * + * @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. + * <p/> + * This convenience method works as if by invoking: + * <p/> + * <blockquote><tt> + * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary, 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. + * <p/> + * <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. + * <p/> + * This convenience method works as if by invoking: + * <p/> + * <blockquote><tt> + * {@link #loadAgent(String, String) loadAgent}(agent, 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. + * <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 <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 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. + * <p/> + * <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/> + * <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; + + return other.provider() == provider() && other.id().equals(id()); + } + + /** + * Returns the string representation of the <code>VirtualMachine</code>. + */ + public String toString() + { + return provider.toString() + ": " + id; + } +} diff --git a/kamon-autoweave/src/main/java/com/sun/tools/attach/VirtualMachineDescriptor.java b/kamon-autoweave/src/main/java/com/sun/tools/attach/VirtualMachineDescriptor.java new file mode 100644 index 00000000..6459e806 --- /dev/null +++ b/kamon-autoweave/src/main/java/com/sun/tools/attach/VirtualMachineDescriptor.java @@ -0,0 +1,208 @@ +/* + * 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 com.sun.tools.attach.spi.AttachProvider; + +/** + * Describes a Java virtual machine. + * <p/> + * <p> A <code>VirtualMachineDescriptor</code> is a container class used to + * describe a Java virtual machine. It encapsulates an identifier that identifies + * a target virtual machine, and a reference to the {@link + * com.sun.tools.attach.spi.AttachProvider AttachProvider} that should be used + * when attempting to attach to the virtual machine. The identifier is + * implementation-dependent but is typically the process identifier (or pid) + * environments where each Java virtual machine runs in its own operating system + * process. </p> + * <p/> + * <p> A <code>VirtualMachineDescriptor</code> also has a {@link #displayName() displayName}. + * The display name is typically a human readable string that a tool might + * display to a user. For example, a tool that shows a list of Java + * virtual machines running on a system might use the display name rather + * than the identifier. A <code>VirtualMachineDescriptor</code> may be + * created without a <i>display name</i>. In that case the identifier is + * used as the <i>display name</i>. + * <p/> + * <p> <code>VirtualMachineDescriptor</code> instances are typically created by + * invoking the {@link VirtualMachine#list VirtualMachine.list()} + * method. This returns the complete list of descriptors to describe the + * Java virtual machines known to all installed {@link + * com.sun.tools.attach.spi.AttachProvider attach providers}. + * + * @since 1.6 + */ +public final class VirtualMachineDescriptor +{ + private AttachProvider provider; + private String id; + private String displayName; + + private volatile int hash; // 0 => not computed + + /** + * Creates a virtual machine descriptor from the given components. + * + * @param provider The AttachProvider to attach to the Java virtual machine. + * @param id The virtual machine identifier. + * @param displayName The display name. + * @throws NullPointerException If any of the arguments are <code>null</code> + */ + public VirtualMachineDescriptor(AttachProvider provider, String id, String displayName) + { + if (provider == null) { + throw new NullPointerException("provider cannot be null"); + } + + if (id == null) { + throw new NullPointerException("identifier cannot be null"); + } + + if (displayName == null) { + throw new NullPointerException("display name cannot be null"); + } + + this.provider = provider; + this.id = id; + this.displayName = displayName; + } + + /** + * Creates a virtual machine descriptor from the given components. + * <p/> + * <p> This convenience constructor works as if by invoking the + * three-argument constructor as follows: + * <p/> + * <blockquote><tt> + * new {@link #VirtualMachineDescriptor(com.sun.tools.attach.spi.AttachProvider, String, String) + * VirtualMachineDescriptor}(provider, id, id); + * </tt></blockquote> + * <p/> + * <p> That is, it creates a virtual machine descriptor such that + * the <i>display name</i> is the same as the virtual machine + * identifier. + * + * @param provider The AttachProvider to attach to the Java virtual machine. + * @param id The virtual machine identifier. + * @throws NullPointerException If <tt>provider</tt> or <tt>id</tt> is <tt>null</tt>. + */ + public VirtualMachineDescriptor(AttachProvider provider, String id) + { + this(provider, id, id); + } + + /** + * Return the <code>AttachProvider</code> that this descriptor references. + * + * @return The <code>AttachProvider</code> that this descriptor references. + */ + public AttachProvider provider() + { + return provider; + } + + /** + * Return the identifier component of this descriptor. + * + * @return The identifier component of this descriptor. + */ + public String id() + { + return id; + } + + /** + * Return the <i>display name</i> component of this descriptor. + * + * @return The display name component of this descriptor. + */ + public String displayName() + { + return displayName; + } + + /** + * Returns a hash-code value for this VirtualMachineDescriptor. The hash + * code is based upon the descriptor's components, and satisfies + * the general contract of the Object.hashCode method. + * + * @return A hash-code value for this descriptor. + */ + public int hashCode() + { + if (hash != 0) { + return hash; + } + + hash = provider.hashCode() * 127 + id.hashCode(); + return hash; + } + + /** + * Tests this VirtualMachineDescriptor for equality with another object. + * <p/> + * <p> If the given object is not a VirtualMachineDescriptor then this + * method returns <tt>false</tt>. For two VirtualMachineDescriptors to + * be considered equal requires that they both reference the same + * provider, and their {@link #id() identifiers} are equal. </p> + * <p/> + * <p> This method satisfies the general contract of the {@link + * 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 VirtualMachineDescriptor that is equal to this + * VirtualMachineDescriptor. + */ + public boolean equals(Object ob) + { + if (ob == this) + return true; + if (!(ob instanceof VirtualMachineDescriptor)) + return false; + VirtualMachineDescriptor other = (VirtualMachineDescriptor) ob; + if (other.provider() != this.provider()) { + return false; + } + if (!other.id().equals(this.id())) { + return false; + } + return true; + } + + /** + * Returns the string representation of the <code>VirtualMachineDescriptor</code>. + */ + public String toString() + { + String s = provider.toString() + ": " + id; + + if (displayName != id) { + s += " " + displayName; + } + + return s; + } +} diff --git a/kamon-autoweave/src/main/java/com/sun/tools/attach/spi/AttachProvider.java b/kamon-autoweave/src/main/java/com/sun/tools/attach/spi/AttachProvider.java new file mode 100644 index 00000000..98e8084d --- /dev/null +++ b/kamon-autoweave/src/main/java/com/sun/tools/attach/spi/AttachProvider.java @@ -0,0 +1,240 @@ +/*
+ * 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.spi;
+
+import com.sun.tools.attach.AttachNotSupportedException;
+import com.sun.tools.attach.VirtualMachine;
+import com.sun.tools.attach.VirtualMachineDescriptor;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.ServiceLoader;
+
+/**
+ * Attach provider class for attaching to a Java virtual machine.
+ * <p/>
+ * <p> An attach provider is a concrete subclass of this class that has a
+ * zero-argument constructor and implements the abstract methods specified
+ * below. </p>
+ * <p/>
+ * <p> An attach provider implementation is typically tied to a Java virtual
+ * machine implementation, version, or even mode of operation. That is, a specific
+ * provider implementation will typically only be capable of attaching to
+ * a specific Java virtual machine implementation or version. For example, Sun's
+ * JDK implementation ships with provider implementations that can only attach to
+ * Sun's <i>HotSpot</i> virtual machine. In general, if an environment
+ * consists of Java virtual machines of different versions and from different
+ * vendors then there will be an attach provider implementation for each
+ * <i>family</i> of implementations or versions. </p>
+ * <p/>
+ * <p> An attach provider is identified by its {@link #name <i>name</i>} and
+ * {@link #type <i>type</i>}. The <i>name</i> is typically, but not required to
+ * be, a name that corresponds to the VM vendor. The Sun JDK implementation,
+ * for example, ships with attach providers that use the name <i>"sun"</i>. The
+ * <i>type</i> typically corresponds to the attach mechanism. For example, an
+ * implementation that uses the Doors inter-process communication mechanism
+ * might use the type <i>"doors"</i>. The purpose of the name and type is to
+ * identify providers in environments where there are multiple providers
+ * installed. </p>
+ * <p/>
+ * <p> AttachProvider implementations are loaded and instantiated at the first
+ * invocation of the {@link #providers() providers} method. This method
+ * attempts to load all provider implementations that are installed on the
+ * platform. </p>
+ * <p/>
+ * <p> All of the methods in this class are safe for use by multiple
+ * concurrent threads. </p>
+ *
+ * @since 1.6
+ */
+public abstract class AttachProvider
+{
+ private static final Object lock = new Object();
+ private static List<AttachProvider> providers;
+
+ /**
+ * Initializes a new instance of this class.
+ */
+ protected AttachProvider() {}
+
+ /**
+ * Return this provider's name.
+ *
+ * @return The name of this provider
+ */
+ public abstract String name();
+
+ /**
+ * Return this provider's type.
+ *
+ * @return The type of this provider
+ */
+ public abstract String type();
+
+ /**
+ * Attaches to a Java virtual machine.
+ * <p/>
+ * <p> A Java virtual machine is identified by an abstract identifier. The
+ * nature of this identifier is platform dependent but in many cases it will be the
+ * string representation of the process identifier (or pid). </p>
+ * <p/>
+ * <p> This method parses the identifier and maps the identifier to a Java
+ * virtual machine (in an implementation dependent manner). If the identifier
+ * cannot be parsed by the provider then an {@link
+ * com.sun.tools.attach.AttachNotSupportedException AttachNotSupportedException}
+ * is thrown. Once parsed this method attempts to attach to the Java virtual machine.
+ * If the provider detects that the identifier corresponds to a Java virtual machine
+ * that does not exist, or it corresponds to a Java virtual machine that does not support
+ * the attach mechanism implemented by this provider, or it detects that the
+ * Java virtual machine is a version to which this provider cannot attach, then
+ * an <code>AttachNotSupportedException</code> is thrown. </p>
+ *
+ * @param id The abstract identifier that identifies the Java virtual machine.
+ * @return VirtualMachine representing the target virtual machine.
+ * @throws SecurityException If a security manager has been installed and it denies
+ * {@link com.sun.tools.attach.AttachPermission AttachPermission}
+ * <tt>("attachVirtualMachine")</tt>, or other permission
+ * required by the implementation.
+ * @throws AttachNotSupportedException If the identifier cannot be parsed, or it corresponds to
+ * to a Java virtual machine that does not exist, or it
+ * corresponds to a Java virtual machine which this
+ * provider cannot attach.
+ * @throws IOException If some other I/O error occurs
+ * @throws NullPointerException If <code>id</code> is <code>null</code>
+ */
+ public abstract VirtualMachine attachVirtualMachine(String id)
+ throws AttachNotSupportedException, IOException;
+
+ /**
+ * Attaches to a Java virtual machine.
+ * <p/>
+ * A Java virtual machine can be described using a {@link
+ * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor}.
+ * This method invokes the descriptor's {@link
+ * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
+ * to check that it is equal to this provider. It then attempts to attach to the
+ * Java virtual machine.
+ *
+ * @param vmd The virtual machine descriptor
+ * @return VirtualMachine representing the target virtual machine.
+ * @throws SecurityException If a security manager has been installed and it denies
+ * {@link com.sun.tools.attach.AttachPermission AttachPermission}
+ * <tt>("attachVirtualMachine")</tt>, or other permission
+ * required by the implementation.
+ * @throws AttachNotSupportedException If the descriptor's {@link
+ * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
+ * returns a provider that is not this provider, or it does not correspond
+ * to a Java virtual machine to which this provider can attach.
+ * @throws IOException If some other I/O error occurs
+ * @throws NullPointerException If <code>vmd</code> is <code>null</code>
+ */
+ public VirtualMachine attachVirtualMachine(VirtualMachineDescriptor vmd)
+ throws AttachNotSupportedException, IOException
+ {
+ if (vmd.provider() != this) {
+ throw new AttachNotSupportedException("provider mismatch");
+ }
+
+ return attachVirtualMachine(vmd.id());
+ }
+
+ /**
+ * Lists the Java virtual machines known to this provider.
+ * <p/>
+ * This method returns a list of {@link com.sun.tools.attach.VirtualMachineDescriptor} elements.
+ * Each <code>VirtualMachineDescriptor</code> describes a Java virtual machine
+ * to which this provider can <i>potentially</i> attach. There isn't any
+ * guarantee that invoking {@link #attachVirtualMachine(VirtualMachineDescriptor)
+ * attachVirtualMachine} on each descriptor in the list will succeed.
+ *
+ * @return The list of virtual machine descriptors which describe the
+ * Java virtual machines known to this provider (may be empty).
+ */
+ public abstract List<VirtualMachineDescriptor> listVirtualMachines();
+
+ /**
+ * Returns a list of the installed attach providers.
+ * <p/>
+ * <p> An AttachProvider is installed on the platform if:
+ * <p/>
+ * <ul>
+ * <li><p>It is installed in a JAR file that is visible to the defining
+ * class loader of the AttachProvider type (usually, but not required
+ * to be, the {@link java.lang.ClassLoader#getSystemClassLoader system
+ * class loader}).</p></li>
+ * <p/>
+ * <li><p>The JAR file contains a provider configuration named
+ * <tt>com.sun.tools.attach.spi.AttachProvider</tt> in the resource directory
+ * <tt>META-INF/services</tt>. </p></li>
+ * <p/>
+ * <li><p>The provider configuration file lists the full-qualified class
+ * name of the AttachProvider implementation. </p></li>
+ * </ul>
+ * <p/>
+ * <p> The format of the provider configuration file is one fully-qualified
+ * class name per line. Space and tab characters surrounding each class name,
+ * as well as blank lines are ignored. The comment character is
+ * <tt>'#'</tt> (<tt>0x23</tt>), and on each line all characters following
+ * the first comment character are ignored. The file must be encoded in
+ * UTF-8. </p>
+ * <p/>
+ * <p> AttachProvider implementations are loaded and instantiated
+ * (using the zero-arg constructor) at the first invocation of this method.
+ * The list returned by the first invocation of this method is the list
+ * of providers. Subsequent invocations of this method return a list of the same
+ * providers. The list is unmodifable.</p>
+ *
+ * @return A list of the installed attach providers.
+ */
+ @SuppressWarnings({"Since15"})
+ public static List<AttachProvider> providers()
+ {
+ synchronized (lock) {
+ if (providers == null) {
+ providers = new ArrayList<AttachProvider>();
+
+ ServiceLoader<AttachProvider> providerLoader =
+ ServiceLoader.load(AttachProvider.class, AttachProvider.class.getClassLoader());
+
+ for (AttachProvider aProviderLoader : providerLoader) {
+ try {
+ providers.add(aProviderLoader);
+ }
+ catch (ThreadDeath td) {
+ throw td;
+ }
+ catch (Throwable t) {
+ // Ignore errors and exceptions.
+ System.err.println(t);
+ }
+ }
+ }
+
+ return Collections.unmodifiableList(providers);
+ }
+ }
+}
|