/*
* 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;
}
}
}