1 /*

     2  * Copyright (c) 2008, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package sun.tracing.dtrace;

    27 

    28 import java.util.Map;

    29 import java.util.Set;

    30 import java.util.HashMap;

    31 import java.util.HashSet;

    32 import java.security.Permission;

    33 

    34 import com.sun.tracing.ProviderFactory;

    35 import com.sun.tracing.Provider;

    36 

    37 /**

    38  * Factory class to create JSDT Providers.

    39  *

    40  * This class contains methods to create an instance of a Provider

    41  * interface which can be used to place tracepoints in an application.

    42  * Method calls upon that instance trigger DTrace probes that

    43  * are visible from DTrace scripts.   Such calls have no other

    44  * side effects in the application.

    45  * <p>

    46  * The DTrace script mechanisms for listing and matching probes will not see

    47  * nor match any probes until the provider they reside in is created by a

    48  * call to {@code createProvider()} (or {@code createProviders()}).

    49  * <p>

    50  * Providers that are created should be disposed of when they are no longer

    51  * needed to free up system resources, at which point the associated

    52  * DTrace probes will no longer be available to DTrace.  One disposes a

    53  * provider by calling

    54  * {@link com.sun.tracing.Provider#dispose Provider.dispose()} on a

    55  * created provider instance.

    56  *

    57  * @since 1.7

    58  */

    59 public final class DTraceProviderFactory extends ProviderFactory {

    60     /**

    61      * Creates an instance of a provider which can then be used to trigger

    62      * DTrace probes.

    63      *

    64      * The provider specification, provided as an argument, should only

    65      * contain methods which have a 'void' return type and String or

    66      * integer-based typed arguments (long, int, short, char, byte, or boolean).

    67      *

    68      * @param cls A user-defined interface which extends {@code Provider}.

    69      * @return An instance of the interface which is used to trigger

    70      * the DTrace probes.

    71      * @throws java.lang.SecurityException if a security manager has been

    72      * installed and it denies

    73      * RuntimePermission("com.sun.dtrace.jsdt.createProvider")

    74      * @throws java.lang.IllegalArgumentException if the interface contains

    75      * methods that do not return null, or that contain arguments that are

    76      * not String or integer types.

    77      */

    78     public <T extends Provider> T createProvider(Class<T> cls) {

    79         DTraceProvider jsdt = new DTraceProvider(cls);

    80         T proxy = jsdt.newProxyInstance();

    81         jsdt.setProxy(proxy);

    82         jsdt.init();

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

    84         return proxy;

    85     }

    86 

    87     /**

    88      * Creates multiple providers at once.

    89      *

    90      * This method batches together a number of provider instantiations.

    91      * It works similarly

    92      * to {@code createProvider}, but operates on a set of providers instead

    93      * of one at a time.  This method is in place since some DTrace

    94      * implementations limit the number of times that providers can be

    95      * created.  When numerous providers can be created at once with this

    96      * method, it will count only as a single creation point to DTrace, thus

    97      * it uses less system resources.

    98      * <p>

    99      * All of the probes in the providers will be visible to DTrace after

   100      * this call and all will remain visible until all of the providers

   101      * are disposed.

   102      * <p>

   103      * The {@code moduleName} parameter will override any {@code ModuleName}

   104      * annotation associated with any of the providers in the set.

   105      * All of the probes created by this call will share the same

   106      * module name.

   107      * <p>

   108      * @param providers a set of provider specification interfaces

   109      * @param moduleName the module name to associate with all probes

   110      * @return A map which maps the provider interface specification to an

   111      * implementing instance.

   112      * @throws java.lang.SecurityException if a security manager has been

   113      * installed and it denies

   114      * RuntimePermission("com.sun.dtrace.jsdt.createProvider")

   115      * @throws java.lang.IllegalArgumentException if any of the interface

   116      * contains methods that do not return null, or that contain arguments

   117      * that are not String or integer types.

   118      */

   119     public Map<Class<? extends Provider>,Provider> createProviders(

   120             Set<Class<? extends Provider>> providers, String moduleName) {

   121         HashMap<Class<? extends Provider>,Provider> map =

   122             new HashMap<Class<? extends Provider>,Provider>();

   123         HashSet<DTraceProvider> jsdts = new HashSet<DTraceProvider>();

   124         for (Class<? extends Provider> cls : providers) {

   125             DTraceProvider jsdt = new DTraceProvider(cls);

   126             jsdts.add(jsdt);

   127             map.put(cls, jsdt.newProxyInstance());

   128         }

   129         new Activation(moduleName, jsdts.toArray(new DTraceProvider[0]));

   130         return map;

   131     }

   132 

   133     /**

   134      * Used to check the status of DTrace support in the underlying JVM and

   135      * operating system.

   136      *

   137      * This is an informative method only - the Java-level effects of

   138      * creating providers and triggering probes will not change whether or

   139      * not DTrace is supported by the underlying systems.

   140      *

   141      * @return true if DTrace is supported

   142      */

   143     public static boolean isSupported() {

   144         try {

   145             SecurityManager security = System.getSecurityManager();

   146             if (security != null) {

   147                 Permission perm = new RuntimePermission(

   148                         "com.sun.tracing.dtrace.createProvider");

   149                 security.checkPermission(perm);

   150             }

   151             return JVM.isSupported();

   152         } catch (SecurityException e) {

   153             return false;

   154         }

   155     }

   156 }