sun.tracing
Class ProviderSkeleton

java.lang.Object
  sun.tracing.ProviderSkeleton

All Implemented Interfaces:

Provider, java.lang.reflect.InvocationHandler

public abstract class ProviderSkeleton
extends java.lang.Object
implements java.lang.reflect.InvocationHandler, Provider

Provides a common code for implementation of Provider classes. Each tracing subsystem needs to provide three classes, a factory (derived from ProviderFactory, a provider (a subclass of Provider, and a probe type (subclass of ProbeSkeleton). The factory object takes a user-defined interface and provides an implementation of it whose method calls will trigger probes in the tracing framework. The framework's provider class, and its instances, are not seen by the user at all -- they usually sit in the background and receive and dispatch the calls to the user's provider interface. The ProviderSkeleton class provides almost all of the implementation needed by a framework provider. Framework providers must only provide a constructor and disposal method, and implement the createProbe method to create an appropriate ProbeSkeleton subclass. The framework's probe class provides the implementation of the two probe methods, isEnabled() and uncheckedTrigger(). Both are framework-dependent implementations.

Since:

1.7

Field Summary

protected boolean	active
protected java.util.HashMap<java.lang.reflect.Method,ProbeSkeleton>	probes
protected java.lang.Class<? extends Provider>	providerType

Constructor Summary

protected

ProviderSkeleton(java.lang.Class<? extends Provider> type) Initializes the provider.

Method Summary

protected abstract ProbeSkeleton	createProbe(java.lang.reflect.Method method) Creates a framework-specific probe subtype.
void	dispose() Default provider disposal method.
protected static java.lang.String	getAnnotationString(java.lang.reflect.AnnotatedElement element, java.lang.Class<? extends java.lang.annotation.Annotation> annotation, java.lang.String defaultValue) Utility method for getting a string value from an annotation.
protected static java.lang.Object	getAnnotationValue(java.lang.reflect.AnnotatedElement element, java.lang.Class<? extends java.lang.annotation.Annotation> annotation, java.lang.String methodName, java.lang.Object defaultValue) Utility method for calling an arbitrary method in an annotation.
Probe	getProbe(java.lang.reflect.Method m) Direct accessor for Probe objects.
protected java.lang.String	getProviderName() Gets the user-specified provider name for the user's interface.
void	init() Post-constructor initialization routine.
java.lang.Object	invoke(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args) Triggers a framework probe when a user interface method is called.
<T extends Provider> T	newProxyInstance() Magic routine which creates an implementation of the user's interface.

Methods inherited from class java.lang.Object

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

Field Detail

active

protected boolean active

providerType

protected java.lang.Class<? extends Provider> providerType

probes

protected java.util.HashMap<java.lang.reflect.Method,ProbeSkeleton> probes

Constructor Detail

ProviderSkeleton

protected ProviderSkeleton(java.lang.Class<? extends Provider> type)

Initializes the provider.

Parameters:

type - the user's interface

Method Detail

createProbe

protected abstract ProbeSkeleton createProbe(java.lang.reflect.Method method)

Creates a framework-specific probe subtype. This method is implemented by the framework's provider and returns framework-specific probes for a method.

Parameters:

method - A method in the user's interface

Returns:

a subclass of ProbeSkeleton for the particular framework.

init

public void init()

Post-constructor initialization routine. Subclass instances must be initialized before they can create probes. It is up to the factory implementations to call this after construction.

newProxyInstance

public <T extends Provider> T newProxyInstance()

Magic routine which creates an implementation of the user's interface. This method creates the instance of the user's interface which is passed back to the user. Every call upon that interface will be redirected to the invoke() method of this class (until overridden by the VM).

Returns:

an implementation of the user's interface

invoke

public java.lang.Object invoke(java.lang.Object proxy,
                               java.lang.reflect.Method method,
                               java.lang.Object[] args)

Triggers a framework probe when a user interface method is called. This method dispatches a user interface method call to the appropriate probe associated with this framework. If the invoked method is not a user-defined member of the interface, then it is a member of Provider or Object and we invoke the method directly.

Specified by:

invoke in interface java.lang.reflect.InvocationHandler

Parameters:

proxy - the instance whose method was invoked

method - the method that was called

args - the arguments passed in the call.

Returns:

always null, if the method is a user-defined probe

getProbe

public Probe getProbe(java.lang.reflect.Method m)

Direct accessor for Probe objects.

Specified by:

getProbe in interface Provider

Parameters:

m - the method corresponding to a probe

Returns:

the method associated probe object, or null

dispose

public void dispose()

Default provider disposal method. This is overridden in subclasses as needed.

Specified by:

dispose in interface Provider

getProviderName

protected java.lang.String getProviderName()

Gets the user-specified provider name for the user's interface. If the user's interface has a annotation, that value is used. Otherwise we use the simple name of the user interface's class.

Returns:

the provider name

getAnnotationString

protected static java.lang.String getAnnotationString(java.lang.reflect.AnnotatedElement element,
                                                      java.lang.Class<? extends java.lang.annotation.Annotation> annotation,
                                                      java.lang.String defaultValue)

Utility method for getting a string value from an annotation. Used for getting a string value from an annotation with a 'value' method.

Parameters:

element - the element that was annotated, either a class or method

annotation - the class of the annotation we're interested in

defaultValue - the value to return if the annotation doesn't exist, doesn't have a "value", or the value is empty.

getAnnotationValue

protected static java.lang.Object getAnnotationValue(java.lang.reflect.AnnotatedElement element,
                                                     java.lang.Class<? extends java.lang.annotation.Annotation> annotation,
                                                     java.lang.String methodName,
                                                     java.lang.Object defaultValue)

Utility method for calling an arbitrary method in an annotation.

Parameters:

element - the element that was annotated, either a class or method

annotation - the class of the annotation we're interested in

methodName - the name of the method in the annotation we wish to call.

defaultValue - the value to return if the annotation doesn't exist, or we couldn't invoke the method for some reason.

Returns:

the result of calling the annotation method, or the default.