sun.tracing.dtrace

Class DTraceProviderFactory

java.lang.Object

com.sun.tracing.ProviderFactory

sun.tracing.dtrace.DTraceProviderFactory

public final class DTraceProviderFactory
extends ProviderFactory

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.

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 createProvider() (or createProviders()).

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 Provider.dispose() on a created provider instance.

Since:

1.7

Constructor Summary

Constructors

Constructor and Description
DTraceProviderFactory()

Method Summary

Methods

Modifier and Type	Method and Description
<T extends Provider> T	createProvider(Class<T> cls) Creates an instance of a provider which can then be used to trigger DTrace probes.
Map<Class<? extends Provider>,Provider>	createProviders(Set<Class<? extends Provider>> providers, String moduleName) Creates multiple providers at once.
static boolean	isSupported() Used to check the status of DTrace support in the underlying JVM and operating system.

Methods inherited from class com.sun.tracing.ProviderFactory

getDefaultFactory

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DTraceProviderFactory

public DTraceProviderFactory()

Method Detail

createProvider

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

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

Specified by:

createProvider in class ProviderFactory

Parameters:

cls - A user-defined interface which extends Provider.

Returns:

An instance of the interface which is used to trigger the DTrace probes.

Throws:

SecurityException - if a security manager has been installed and it denies RuntimePermission("com.sun.dtrace.jsdt.createProvider")

IllegalArgumentException - if the interface contains methods that do not return null, or that contain arguments that are not String or integer types.

createProviders

public Map<Class<? extends Provider>,Provider> createProviders(Set<Class<? extends Provider>> providers,
                                                      String moduleName)

Creates multiple providers at once. This method batches together a number of provider instantiations. It works similarly to 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.

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.

The moduleName parameter will override any 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.

Parameters:

providers - a set of provider specification interfaces

moduleName - the module name to associate with all probes

Returns:

A map which maps the provider interface specification to an implementing instance.

Throws:

SecurityException - if a security manager has been installed and it denies RuntimePermission("com.sun.dtrace.jsdt.createProvider")

IllegalArgumentException - if any of the interface contains methods that do not return null, or that contain arguments that are not String or integer types.

isSupported

public static boolean isSupported()

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.

Returns:

true if DTrace is supported