Java example source code file (AttachProvider.java)

This example Java source code file (AttachProvider.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

arraylist, attachnotsupportedexception, attachpermission, attachprovider, ioexception, iterator, list, object, securitymanager, serviceloader, string, threaddeath, throwable, util, virtualmachine

The AttachProvider.java Java example source code

/*
 * 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 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 of implementations or versions. 

 *
 * <p> An attach provider is identified by its {@link #name name} and
 * {@link #type <i>type}. The name 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". The
 * <i>type typically corresponds to the attach mechanism. For example, an
 * implementation that uses the Doors inter-process communication mechanism
 * might use the type <i>"doors". 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")
     */
    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 is thrown. 

     *
     * @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"), 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 is null
     */
    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"), 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 is null
     */
    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 describes a Java virtual machine
     * to which this provider can <i>potentially 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>
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>
The JAR file contains a provider configuration named
     *   <tt>com.sun.tools.attach.spi.AttachProvider in the resource directory
     *   <tt>META-INF/services. 
     *
     *   <li>
The provider configuration file lists the full-qualified class
     *   name of the AttachProvider implementation. </p>
     * </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>'#' (0x23), 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);
        }
    }
}