/*

 */

package sun.tracing.dtrace;

import java.util.Map;

import java.util.Set;

import java.util.HashMap;

import java.util.HashSet;

import java.util.logging.Logger;

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);

        try {

            jsdt.init();

            new Activation(jsdt.getModuleName(), new DTraceProvider[] { jsdt });

        } catch (Exception e) {

            // Probably a permission problem (can't get declared members)

            Logger.getAnonymousLogger().warning(

                "Could not initialize tracing provider: " + e.getMessage());

            jsdt.dispose();

        }

        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;

        }

    }

}