linkerlau/my-jdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(jdk8): move files to new folder to avoid resources compiled.

Browse Source
This commit is contained in:
linkerlau
2025-09-07 15:25:52 +08:00
parent 3f0047bf6f
commit 8c35cfb1c0
17415 changed files with 217 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
jdkSrc/jdk8/com/sun/tools/attach/AgentInitializationException.java Normal file
View File

@@ -0,0 +1,95 @@
/*
* Copyright (c) 2005, 2013, 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;
/**
* The exception thrown when an agent fails to initialize in the target
* Java virtual machine.
*
* <p> This exception is thrown by {@link
* com.sun.tools.attach.VirtualMachine#loadAgent VirtualMachine.loadAgent},
* {@link com.sun.tools.attach.VirtualMachine#loadAgentLibrary
* VirtualMachine.loadAgentLibrary}, {@link
* com.sun.tools.attach.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.
*/
@jdk.Exported
public class AgentInitializationException extends Exception {
/** use serialVersionUID for interoperability */
static final long serialVersionUID = -1508756333332806353L;
private int returnValue;
/**
* Constructs an <code>AgentInitializationException</code> with
* no detail message.
*/
public AgentInitializationException() {
super();
this.returnValue = 0;
}
/**
* Constructs an <code>AgentInitializationException</code> with
* the specified detail message.
*
* @param s the detail message.
*/
public AgentInitializationException(String s) {
super(s);
this.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>
*
* @return the return value
*/
public int returnValue() {
return returnValue;
}
}

63
jdkSrc/jdk8/com/sun/tools/attach/AgentLoadException.java Normal file
View File

@@ -0,0 +1,63 @@
/*
* Copyright (c) 2005, 2013, 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;
/**
* The exception thrown when an agent cannot be loaded into the target
* Java virtual machine.
*
* <p> This exception is thrown by {@link
* com.sun.tools.attach.VirtualMachine#loadAgent VirtualMachine.loadAgent} or
* {@link com.sun.tools.attach.VirtualMachine#loadAgentLibrary
* VirtualMachine.loadAgentLibrary}, {@link
* com.sun.tools.attach.VirtualMachine#loadAgentPath loadAgentPath} methods
* if the agent, or agent library, cannot be loaded.
*/
@jdk.Exported
public class AgentLoadException extends Exception {
/** use serialVersionUID for interoperability */
static final long serialVersionUID = 688047862952114238L;
/**
* Constructs an <code>AgentLoadException</code> with
* no detail message.
*/
public AgentLoadException() {
super();
}
/**
* Constructs an <code>AgentLoadException</code> with
* the specified detail message.
*
* @param s the detail message.
*/
public AgentLoadException(String s) {
super(s);
}
}

64
jdkSrc/jdk8/com/sun/tools/attach/AttachNotSupportedException.java Normal file
View File

@@ -0,0 +1,64 @@
/*
* Copyright (c) 2005, 2013, 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; // for javadoc
/**
* Thrown by {@link com.sun.tools.attach.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 comptatible.
*/
@jdk.Exported
public class AttachNotSupportedException extends Exception {
/** use serialVersionUID for interoperability */
static final long serialVersionUID = 3391824968260177264L;
/**
* Constructs an <code>AttachNotSupportedException</code> with
* no detail message.
*/
public AttachNotSupportedException() {
super();
}
/**
* Constructs an <code>AttachNotSupportedException</code> with
* the specified detail message.
*
* @param s the detail message.
*/
public AttachNotSupportedException(String s) {
super(s);
}
}

54
jdkSrc/jdk8/com/sun/tools/attach/AttachOperationFailedException.java Normal file
View File

@@ -0,0 +1,54 @@
/*
* Copyright (c) 2014, 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 java.io.IOException;
/**
* Exception type to signal that an attach operation failed in the target VM.
*
* <p> This exception can be thrown by the various operations of
* {@link com.sun.tools.attach.VirtualMachine} when the operation
* fails in the target VM. If there is a communication error,
* a regular IOException will be thrown.
*
* @since 1.9
*/
@jdk.Exported
public class AttachOperationFailedException extends IOException {
private static final long serialVersionUID = 2140308168167478043L;
/**
* Constructs an <code>AttachOperationFailedException</code> with
* the specified detail message.
*
* @param s the detail message.
*/
public AttachOperationFailedException(String message) {
super(message);
}
}

125
jdkSrc/jdk8/com/sun/tools/attach/AttachPermission.java Normal file
View File

@@ -0,0 +1,125 @@
/*
* Copyright (c) 2005, 2013, 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;
/**
* When a {@link java.lang.SecurityManager SecurityManager} set, this
* is the permission which will be checked when code invokes {@link
* VirtualMachine#attach VirtalMachine.attach} to attach to a target virtual
* machine.
* This permission is also checked when an {@link
* com.sun.tools.attach.spi.AttachProvider AttachProvider} is created. </p>
*
* <p> An <code>AttachPermission</code> object contains a name (also referred
* to as a "target name") but no actions list; you either have the
* named permission or you don't.
* The following table provides a summary description of what the
* permission allows, and discusses the risks of granting code the
* permission.
* <P>
* <table border=1 cellpadding=5 summary="Table shows permission
* target name, what the permission allows, and associated risks">
* <tr>
* <th>Permission Target Name</th>
* <th>What the Permission Allows</th>
* <th>Risks of Allowing this Permission</th>
* </tr>
*
* <tr>
* <td>attachVirtualMachine</td>
* <td>Ability to attach to another Java virtual machine and load agents
* into that VM.
* </td>
* <td>This allows an attacker to control the target VM which can potentially
* cause it to misbehave.
* </td>
* </tr>
*
* <tr>
* <td>createAttachProvider</td>
* <td>Ability to create an <code>AttachProvider</code> instance.
* </td>
* <td>This allows an attacker to create an AttachProvider which can
* potentially be used to attach to other Java virtual machines.
* </td>
* </tr>
*
* </table>
* <p>
* Programmers do not normally create AttachPermission objects directly.
* Instead they are created by the security policy code based on reading
* the security policy file.
*
* @see com.sun.tools.attach.VirtualMachine
* @see com.sun.tools.attach.spi.AttachProvider
*/
@jdk.Exported
public final class AttachPermission extends java.security.BasicPermission {
/** use serialVersionUID for interoperability */
static final long serialVersionUID = -4619447669752976181L;
/**
* Constructs a new AttachPermission object.
*
* @param name Permission name. Must be either "attachVirtualMachine",
* or "createAttachProvider".
*
* @throws NullPointerException if name is <code>null</code>.
* @throws IllegalArgumentException if the name is invalid.
*/
public AttachPermission(String name) {
super(name);
if (!name.equals("attachVirtualMachine") && !name.equals("createAttachProvider")) {
throw new IllegalArgumentException("name: " + name);
}
}
/**
* Constructs a new AttachPermission object.
*
* @param name Permission name. Must be either "attachVirtualMachine",
* or "createAttachProvider".
*
* @param actions Not used and should be <code>null</code>, or
* the empty string.
*
* @throws NullPointerException if name is <code>null</code>.
* @throws IllegalArgumentException if arguments are invalid.
*/
public AttachPermission(String name, String actions) {
super(name);
if (!name.equals("attachVirtualMachine") && !name.equals("createAttachProvider")) {
throw new IllegalArgumentException("name: " + name);
}
if (actions != null && actions.length() > 0) {
throw new IllegalArgumentException("actions: " + actions);
}
}
}

723
jdkSrc/jdk8/com/sun/tools/attach/VirtualMachine.java Normal file
View File

@@ -0,0 +1,723 @@
/*
* Copyright (c) 2005, 2014, 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.
*
* <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 either in a dynamic library or statically linked into the VM 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");
*
* // start management agent
* Properties props = new Properties();
* props.put("com.sun.management.jmxremote.port", "5000");
* vm.startManagementAgent(props);
*
* // 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>. Then the JMX management agent is
* started in the target process using the supplied arguments. Finally, the
* client detaches from the target VM. </p>
*
* <p> A VirtualMachine is safe for use by multiple concurrent threads. </p>
*
* @since 1.6
*/
@jdk.Exported
public abstract class VirtualMachine {
private AttachProvider provider;
private 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.
*
* @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.
*
* <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.
*
* <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.
*
* <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. </p>
*
* @throws IOException
* If an I/O error occurs
*/
public abstract void detach() throws IOException;
/**
* 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.
*
* @return 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. Alternatively, it may be statically linked into the VM.
* This method causes the given agent library to be loaded into the target
* VM (if not already loaded or if not statically linked into the VM).
* It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
* or, for a statically linked agent named 'L', the <code>Agent_OnAttach_L</code> function
* as specified in the
* <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
* Interface</a> specification. Note that the <code>Agent_OnAttach[_L]</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>L</tt> might be expanded to
* <tt>libL.so</tt>, and located using the search path specified by the
* <tt>LD_LIBRARY_PATH</tt> environment variable. If the agent named 'L' is
* statically linked into the VM then the VM must export a function named
* <code>Agent_OnAttach_L</code>.</p>
*
* <p> If the <code>Agent_OnAttach[_L]</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[_L]</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[_L]</code>
* function (can be <code>null</code>).
*
* @throws AgentLoadException
* If the agent library does not exist, the agent library is not
* statically linked with the VM, or the agent library cannot be
* loaded for another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach[_L]</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:
*
* <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, the agent library is not
* statically linked with the VM, or the agent library cannot be
* loaded for another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach[_L]</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. Alternatively, the native
* library specified by the agentPath parameter may be statically
* linked with the VM. The parsing of the agentPath parameter into
* a statically linked library name is done in a platform
* specific manner in the VM. For example, in UNIX, an agentPath parameter
* of <code>/a/b/libL.so</code> would name a library 'L'.
*
* See the JVM TI Specification for more details.
*
* This method causes the given agent library to be loaded into the target
* VM (if not already loaded or if not statically linked into the VM).
* It then causes the target VM to invoke the <code>Agent_OnAttach</code>
* function or, for a statically linked agent named 'L', the
* <code>Agent_OnAttach_L</code> function as specified in the
* <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
* Interface</a> specification.
* Note that the <code>Agent_OnAttach[_L]</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[_L]</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[_L]</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[_L]</code>
* function (can be <code>null</code>).
*
* @throws AgentLoadException
* If the agent library does not exist, the agent library is not
* statically linked with the VM, or the agent library cannot be
* loaded for another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach[_L]</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:
*
* <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, the agent library is not
* statically linked with the VM, or the agent library cannot be
* loaded for another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach[_L]</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> 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:
*
* <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.
*
* <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 AttachOperationFailedException
* If the target virtual machine is unable to complete the
* attach operation. A more specific error message will be
* given by {@link AttachOperationFailedException#getMessage()}.
*
* @throws IOException
* If an I/O error occurs, a communication error for example,
* that cannot be identified as an error to indicate that the
* operation failed in the target VM.
*
* @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 AttachOperationFailedException
* If the target virtual machine is unable to complete the
* attach operation. A more specific error message will be
* given by {@link AttachOperationFailedException#getMessage()}.
*
* @throws IOException
* If an I/O error occurs, a communication error for example,
* that cannot be identified as an error to indicate that the
* operation failed in the target VM.
*/
public abstract Properties getAgentProperties() throws IOException;
/**
* Starts the JMX management agent in the target virtual machine.
*
* <p> The configuration properties are the same as those specified on
* the command line when starting the JMX management agent. In the same
* way as on the command line, you need to specify at least the
* {@code com.sun.management.jmxremote.port} property.
*
* <p> See the online documentation for <a
* href="../../../../../../../../technotes/guides/management/agent.html">
* Monitoring and Management Using JMX Technology</a> for further details.
*
* @param agentProperties
* A Properties object containing the configuration properties
* for the agent.
*
* @throws AttachOperationFailedException
* If the target virtual machine is unable to complete the
* attach operation. A more specific error message will be
* given by {@link AttachOperationFailedException#getMessage()}.
*
* @throws IOException
* If an I/O error occurs, a communication error for example,
* that cannot be identified as an error to indicate that the
* operation failed in the target VM.
*
* @throws IllegalArgumentException
* If keys or values in agentProperties are invalid.
*
* @throws NullPointerException
* If agentProperties is null.
*
* @since 1.8
*/
public abstract void startManagementAgent(Properties agentProperties) throws IOException;
/**
* Starts the local JMX management agent in the target virtual machine.
*
* <p> See the online documentation for <a
* href="../../../../../../../../technotes/guides/management/agent.html">
* Monitoring and Management Using JMX Technology</a> for further details.
*
* @return The String representation of the local connector's service address.
* The value can be parsed by the
* {@link javax.management.remote.JMXServiceURL#JMXServiceURL(String)}
* constructor.
*
* @throws AttachOperationFailedException
* If the target virtual machine is unable to complete the
* attach operation. A more specific error message will be
* given by {@link AttachOperationFailedException#getMessage()}.
*
* @throws IOException
* If an I/O error occurs, a communication error for example,
* that cannot be identified as an error to indicate that the
* operation failed in the target VM.
*
* @since 1.8
*/
public abstract String startLocalManagementAgent() 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 {@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.
*
* <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 <code>VirtualMachine</code>.
*/
public String toString() {
return provider.toString() + ": " + id;
}
}

204
jdkSrc/jdk8/com/sun/tools/attach/VirtualMachineDescriptor.java Normal file
View File

@@ -0,0 +1,204 @@
/*
* Copyright (c) 2005, 2013, 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;
/**
* Describes a Java virtual machine.
*
* <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> 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> <code>VirtualMachineDescriptor</code> instances are typically created by
* invoking the {@link com.sun.tools.attach.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
*/
@jdk.Exported
public 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> This convenience constructor works as if by invoking the
* three-argument constructor as follows:
*
* <blockquote><tt>
* new&nbsp;{@link #VirtualMachineDescriptor(AttachProvider, String, String)
* VirtualMachineDescriptor}(provider, &nbsp;id, &nbsp;id);
* </tt></blockquote>
*
* <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 satifies
* the general contract of the {@link java.lang.Object#hashCode()
* 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> 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> 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 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;
}
}

43
jdkSrc/jdk8/com/sun/tools/attach/package-info.java Normal file
View File

@@ -0,0 +1,43 @@
/*
* Copyright (c) 2005, 2013, 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.
*/
/**
* Provides the API to attach to a Java<sup><font size=-2>TM</font></sup>
* virtual machine.
* <p>
* A tool, written in the Java Language, uses this API to attach to a target
* virtual machine (VM) and load its tool agent into the target VM. For
* example, a management console might have a management agent which it uses
* to obtain management information from instrumented objects in a Java
* virtual machine. If the management console is required to manage
* an application that is running in a virtual machine that does not include
* the management agent, then this API can be used to attach to the target
* VM and load the agent.
*
* @since 1.6
*/
@jdk.Exported
package com.sun.tools.attach;

274
jdkSrc/jdk8/com/sun/tools/attach/spi/AttachProvider.java Normal file
View File

@@ -0,0 +1,274 @@
/*
* Copyright (c) 2005, 2013, 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.spi;
import java.io.IOException;
import java.util.Collections;
import java.util.Iterator;
import java.util.ArrayList;
import java.util.List;
import com.sun.tools.attach.VirtualMachine;
import com.sun.tools.attach.VirtualMachineDescriptor;
import com.sun.tools.attach.AttachPermission;
import com.sun.tools.attach.AttachNotSupportedException;
import java.util.ServiceLoader;
/**
* Attach provider class for attaching to a Java virtual machine.
*
* <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> 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> 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> 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> All of the methods in this class are safe for use by multiple
* concurrent threads. </p>
*
* @since 1.6
*/
@jdk.Exported
public abstract class AttachProvider {
private static final Object lock = new Object();
private static List<AttachProvider> providers = null;
/**
* Initializes a new instance of this class. </p>
*
* @throws SecurityException
* If a security manager has been installed and it denies
* {@link com.sun.tools.attach.AttachPermission AttachPermission}
* <tt>("createAttachProvider")</tt>
*/
protected AttachProvider() {
SecurityManager sm = System.getSecurityManager();
if (sm != null)
sm.checkPermission(new AttachPermission("createAttachProvider"));
}
/**
* Return this provider's name. </p>
*
* @return The name of this provider
*/
public abstract String name();
/**
* Return this provider's type. </p>
*
* @return The type of this provider
*/
public abstract String type();
/**
* Attaches to a Java virtual machine.
*
* <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> 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> An AttachProvider is installed on the platform if:
*
* <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>
*
* <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>
*
* <li><p>The provider configuration file lists the full-qualified class
* name of the AttachProvider implementation. </p></li>
* </ul>
*
* <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> 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.
*/
public static List<AttachProvider> providers() {
synchronized (lock) {
if (providers == null) {
providers = new ArrayList<AttachProvider>();
ServiceLoader<AttachProvider> providerLoader =
ServiceLoader.load(AttachProvider.class,
AttachProvider.class.getClassLoader());
Iterator<AttachProvider> i = providerLoader.iterator();
while (i.hasNext()) {
try {
providers.add(i.next());
} catch (Throwable t) {
if (t instanceof ThreadDeath) {
ThreadDeath td = (ThreadDeath)t;
throw td;
}
// Ignore errors and exceptions
System.err.println(t);
}
}
}
return Collections.unmodifiableList(providers);
}
}
}

35
jdkSrc/jdk8/com/sun/tools/attach/spi/package-info.java Normal file
View File

@@ -0,0 +1,35 @@
/*
* Copyright (c) 2005, 2013, 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.
*/
/**
* Only developers who are defining new attach providers should need to make
* direct use of this package.
*
* @since 1.6
*/
@jdk.Exported
package com.sun.tools.attach.spi;