001: /*
002: * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.tools.attach.spi;
027:
028: import java.io.IOException;
029: import java.util.Collections;
030: import java.util.Iterator;
031: import java.util.ArrayList;
032: import java.util.List;
033: import com.sun.tools.attach.VirtualMachine;
034: import com.sun.tools.attach.VirtualMachineDescriptor;
035: import com.sun.tools.attach.AttachPermission;
036: import com.sun.tools.attach.AttachNotSupportedException;
037: import java.util.ServiceLoader;
038:
039: /**
040: * Attach provider class for attaching to a Java virtual machine.
041: *
042: * <p> An attach provider is a concrete subclass of this class that has a
043: * zero-argument constructor and implements the abstract methods specified
044: * below. </p>
045: *
046: * <p> An attach provider implementation is typically tied to a Java virtual
047: * machine implementation, version, or even mode of operation. That is, a specific
048: * provider implementation will typically only be capable of attaching to
049: * a specific Java virtual machine implementation or version. For example, Sun's
050: * JDK implementation ships with provider implementations that can only attach to
051: * Sun's <i>HotSpot</i> virtual machine. In general, if an environment
052: * consists of Java virtual machines of different versions and from different
053: * vendors then there will be an attach provider implementation for each
054: * <i>family</i> of implementations or versions. </p>
055: *
056: * <p> An attach provider is identified by its {@link #name <i>name</i>} and
057: * {@link #type <i>type</i>}. The <i>name</i> is typically, but not required to
058: * be, a name that corresponds to the VM vendor. The Sun JDK implementation,
059: * for example, ships with attach providers that use the name <i>"sun"</i>. The
060: * <i>type</i> typically corresponds to the attach mechanism. For example, an
061: * implementation that uses the Doors inter-process communication mechanism
062: * might use the type <i>"doors"</i>. The purpose of the name and type is to
063: * identify providers in environments where there are multiple providers
064: * installed. </p>
065: *
066: * <p> AttachProvider implementations are loaded and instantiated at the first
067: * invocation of the {@link #providers() providers} method. This method
068: * attempts to load all provider implementations that are installed on the
069: * platform. </p>
070: *
071: * <p> All of the methods in this class are safe for use by multiple
072: * concurrent threads. </p>
073: *
074: * @since 1.6
075: */
076:
077: public abstract class AttachProvider {
078:
079: private static final Object lock = new Object();
080: private static List<AttachProvider> providers = null;
081:
082: /**
083: * Initializes a new instance of this class. </p>
084: *
085: * @throws SecurityException
086: * If a security manager has been installed and it denies
087: * {@link com.sun.tools.attach.AttachPermission AttachPermission}
088: * <tt>("createAttachProvider")</tt>
089: */
090: protected AttachProvider() {
091: SecurityManager sm = System.getSecurityManager();
092: if (sm != null)
093: sm.checkPermission(new AttachPermission(
094: "createAttachProvider"));
095: }
096:
097: /**
098: * Return this provider's name. </p>
099: *
100: * @return The name of this provider
101: */
102: public abstract String name();
103:
104: /**
105: * Return this provider's type. </p>
106: *
107: * @return The type of this provider
108: */
109: public abstract String type();
110:
111: /**
112: * Attaches to a Java virtual machine.
113: *
114: * <p> A Java virtual machine is identified by an abstract identifier. The
115: * nature of this identifier is platform dependent but in many cases it will be the
116: * string representation of the process identifier (or pid). </p>
117: *
118: * <p> This method parses the identifier and maps the identifier to a Java
119: * virtual machine (in an implementation dependent manner). If the identifier
120: * cannot be parsed by the provider then an {@link
121: * com.sun.tools.attach.AttachNotSupportedException AttachNotSupportedException}
122: * is thrown. Once parsed this method attempts to attach to the Java virtual machine.
123: * If the provider detects that the identifier corresponds to a Java virtual machine
124: * that does not exist, or it corresponds to a Java virtual machine that does not support
125: * the attach mechanism implemented by this provider, or it detects that the
126: * Java virtual machine is a version to which this provider cannot attach, then
127: * an <code>AttachNotSupportedException</code> is thrown. </p>
128: *
129: * @param id
130: * The abstract identifier that identifies the Java virtual machine.
131: *
132: * @return VirtualMachine representing the target virtual machine.
133: *
134: * @throws SecurityException
135: * If a security manager has been installed and it denies
136: * {@link com.sun.tools.attach.AttachPermission AttachPermission}
137: * <tt>("attachVirtualMachine")</tt>, or other permission
138: * required by the implementation.
139: *
140: * @throws AttachNotSupportedException
141: * If the identifier cannot be parsed, or it corresponds to
142: * to a Java virtual machine that does not exist, or it
143: * corresponds to a Java virtual machine which this
144: * provider cannot attach.
145: *
146: * @throws IOException
147: * If some other I/O error occurs
148: *
149: * @throws NullPointerException
150: * If <code>id</code> is <code>null</code>
151: */
152: public abstract VirtualMachine attachVirtualMachine(String id)
153: throws AttachNotSupportedException, IOException;
154:
155: /**
156: * Attaches to a Java virtual machine.
157: *
158: * <p> A Java virtual machine can be described using a {@link
159: * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor}.
160: * This method invokes the descriptor's {@link
161: * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
162: * to check that it is equal to this provider. It then attempts to attach to the
163: * Java virtual machine.
164: *
165: * @param vmd
166: * The virtual machine descriptor
167: *
168: * @return VirtualMachine representing the target virtual machine.
169: *
170: * @throws SecurityException
171: * If a security manager has been installed and it denies
172: * {@link com.sun.tools.attach.AttachPermission AttachPermission}
173: * <tt>("attachVirtualMachine")</tt>, or other permission
174: * required by the implementation.
175: *
176: * @throws AttachNotSupportedException
177: * If the descriptor's {@link
178: * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
179: * returns a provider that is not this provider, or it does not correspond
180: * to a Java virtual machine to which this provider can attach.
181: *
182: * @throws IOException
183: * If some other I/O error occurs
184: *
185: * @throws NullPointerException
186: * If <code>vmd</code> is <code>null</code>
187: */
188: public VirtualMachine attachVirtualMachine(
189: VirtualMachineDescriptor vmd)
190: throws AttachNotSupportedException, IOException {
191: if (vmd.provider() != this ) {
192: throw new AttachNotSupportedException("provider mismatch");
193: }
194: return attachVirtualMachine(vmd.id());
195: }
196:
197: /**
198: * Lists the Java virtual machines known to this provider.
199: *
200: * <p> This method returns a list of {@link
201: * com.sun.tools.attach.VirtualMachineDescriptor} elements. Each
202: * <code>VirtualMachineDescriptor</code> describes a Java virtual machine
203: * to which this provider can <i>potentially</i> attach. There isn't any
204: * guarantee that invoking {@link #attachVirtualMachine(VirtualMachineDescriptor)
205: * attachVirtualMachine} on each descriptor in the list will succeed.
206: *
207: * @return The list of virtual machine descriptors which describe the
208: * Java virtual machines known to this provider (may be empty).
209: */
210: public abstract List<VirtualMachineDescriptor> listVirtualMachines();
211:
212: /**
213: * Returns a list of the installed attach providers.
214: *
215: * <p> An AttachProvider is installed on the platform if:
216: *
217: * <ul>
218: * <li><p>It is installed in a JAR file that is visible to the defining
219: * class loader of the AttachProvider type (usually, but not required
220: * to be, the {@link java.lang.ClassLoader#getSystemClassLoader system
221: * class loader}).</p></li>
222: *
223: * <li><p>The JAR file contains a provider configuration named
224: * <tt>com.sun.tools.attach.spi.AttachProvider</tt> in the resource directory
225: * <tt>META-INF/services</tt>. </p></li>
226: *
227: * <li><p>The provider configuration file lists the full-qualified class
228: * name of the AttachProvider implementation. </p></li>
229: * </ul>
230: *
231: * <p> The format of the provider configuration file is one fully-qualified
232: * class name per line. Space and tab characters surrounding each class name,
233: * as well as blank lines are ignored. The comment character is
234: * <tt>'#'</tt> (<tt>0x23</tt>), and on each line all characters following
235: * the first comment character are ignored. The file must be encoded in
236: * UTF-8. </p>
237: *
238: * <p> AttachProvider implementations are loaded and instantiated
239: * (using the zero-arg constructor) at the first invocation of this method.
240: * The list returned by the first invocation of this method is the list
241: * of providers. Subsequent invocations of this method return a list of the same
242: * providers. The list is unmodifable.</p>
243: *
244: * @return A list of the installed attach providers.
245: */
246: public static List<AttachProvider> providers() {
247: synchronized (lock) {
248: if (providers == null) {
249: providers = new ArrayList<AttachProvider>();
250:
251: ServiceLoader<AttachProvider> providerLoader = ServiceLoader
252: .load(AttachProvider.class,
253: AttachProvider.class.getClassLoader());
254:
255: Iterator<AttachProvider> i = providerLoader.iterator();
256:
257: while (i.hasNext()) {
258: try {
259: providers.add((AttachProvider) i.next());
260: } catch (Throwable t) {
261: if (t instanceof ThreadDeath) {
262: ThreadDeath td = (ThreadDeath) t;
263: throw td;
264: }
265: // Ignore errors and exceptions
266: System.err.println(t);
267: }
268: }
269: }
270: return Collections.unmodifiableList(providers);
271: }
272: }
273: }
|