DTraceProviderFactory.java

/*
 * Copyright (c) 2008, 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 sun.tracing.dtrace;

import java.util.Map;
import java.util.Set;
import java.util.HashMap;
import java.util.HashSet;
import java.security.Permission;

import com.sun.tracing.ProviderFactory;
import com.sun.tracing.Provider;

/**
 * Factory class to create JSDT Providers.
 *
 * This class contains methods to create an instance of a Provider
 * interface which can be used to place tracepoints in an application.
 * Method calls upon that instance trigger DTrace probes that
 * are visible from DTrace scripts.   Such calls have no other
 * side effects in the application.
 * <p>
 * The DTrace script mechanisms for listing and matching probes will not see
 * nor match any probes until the provider they reside in is created by a
 * call to {@code createProvider()} (or {@code createProviders()}).
 * <p>
 * Providers that are created should be disposed of when they are no longer
 * needed to free up system resources, at which point the associated
 * DTrace probes will no longer be available to DTrace.  One disposes a
 * provider by calling
 * {@link com.sun.tracing.Provider#dispose Provider.dispose()} on a
 * created provider instance.
 *
 * @since 1.7
 */
public final class DTraceProviderFactory extends ProviderFactory {
    /**
     * Creates an instance of a provider which can then be used to trigger
     * DTrace probes.
     *
     * The provider specification, provided as an argument, should only
     * contain methods which have a 'void' return type and String or
     * integer-based typed arguments (long, int, short, char, byte, or boolean).
     *
     * @param cls A user-defined interface which extends {@code Provider}.
     * @return An instance of the interface which is used to trigger
     * the DTrace probes.
     * @throws java.lang.SecurityException if a security manager has been
     * installed and it denies
     * RuntimePermission("com.sun.dtrace.jsdt.createProvider")
     * @throws java.lang.IllegalArgumentException if the interface contains
     * methods that do not return null, or that contain arguments that are
     * not String or integer types.
     */
    public <T extends Provider> T createProvider(Class<T> cls) {
        DTraceProvider jsdt = new DTraceProvider(cls);
        T proxy = jsdt.newProxyInstance();
        jsdt.setProxy(proxy);
        jsdt.init();
        new Activation(jsdt.getModuleName(), new DTraceProvider[] { jsdt });
        return proxy;
    }

    /**
     * Creates multiple providers at once.
     *
     * This method batches together a number of provider instantiations.
     * It works similarly
     * to {@code createProvider}, but operates on a set of providers instead
     * of one at a time.  This method is in place since some DTrace
     * implementations limit the number of times that providers can be
     * created.  When numerous providers can be created at once with this
     * method, it will count only as a single creation point to DTrace, thus
     * it uses less system resources.
     * <p>
     * All of the probes in the providers will be visible to DTrace after
     * this call and all will remain visible until all of the providers
     * are disposed.
     * <p>
     * The {@code moduleName} parameter will override any {@code ModuleName}
     * annotation associated with any of the providers in the set.
     * All of the probes created by this call will share the same
     * module name.
     * <p>
     * @param providers a set of provider specification interfaces
     * @param moduleName the module name to associate with all probes
     * @return A map which maps the provider interface specification to an
     * implementing instance.
     * @throws java.lang.SecurityException if a security manager has been
     * installed and it denies
     * RuntimePermission("com.sun.dtrace.jsdt.createProvider")
     * @throws java.lang.IllegalArgumentException if any of the interface
     * contains methods that do not return null, or that contain arguments
     * that are not String or integer types.
     */
    public Map<Class<? extends Provider>,Provider> createProviders(
            Set<Class<? extends Provider>> providers, String moduleName) {
        HashMap<Class<? extends Provider>,Provider> map =
            new HashMap<Class<? extends Provider>,Provider>();
        HashSet<DTraceProvider> jsdts = new HashSet<DTraceProvider>();
        for (Class<? extends Provider> cls : providers) {
            DTraceProvider jsdt = new DTraceProvider(cls);
            jsdts.add(jsdt);
            map.put(cls, jsdt.newProxyInstance());
        }
        new Activation(moduleName, jsdts.toArray(new DTraceProvider[0]));
        return map;
    }

    /**
     * Used to check the status of DTrace support in the underlying JVM and
     * operating system.
     *
     * This is an informative method only - the Java-level effects of
     * creating providers and triggering probes will not change whether or
     * not DTrace is supported by the underlying systems.
     *
     * @return true if DTrace is supported
     */
    public static boolean isSupported() {
        try {
            SecurityManager security = System.getSecurityManager();
            if (security != null) {
                Permission perm = new RuntimePermission(
                        "com.sun.tracing.dtrace.createProvider");
                security.checkPermission(perm);
            }
            return JVM.isSupported();
        } catch (SecurityException e) {
            return false;
        }
    }
}