Java example source code file (DTraceProviderFactory.java)

This example Java source code file (DTraceProviderFactory.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

activation, class, dtraceprovider, dtraceproviderfactory, hashmap, hashset, permission, provider, runtimepermission, security, securityexception, securitymanager, string, util

The DTraceProviderFactory.java Java example source code

/*
 * 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 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 createProviders(
            Set<Class providers, String moduleName) {
        HashMap<Class map =
            new HashMap<Class();
        HashSet<DTraceProvider> jsdts = new HashSet();
        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;
        }
    }
}