/* * Copyright (c) 2005, 2006, 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 */ 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);        }    }}