javax.slee.facilities

Interface Tracer

public interface Tracer

The Tracer interface is used to emit trace messages. Trace messages that are emitted and which are not filtered by the effective trace filter level setting for the tracer cause a TraceNotification to be generated by the TraceMBean.

A tracer is a named entity. Tracer names are case-sensitive and follow the Java hierarchical naming conventions. A tracer is considered to be an ancestor of another tracer if its name followed by a dot is a prefix of the descendant tracer's name. A tracer is considered to be a parent of a child tracer if there are no ancestors between itself and the descendant tracer. For example, the tracer named "com" is the parent tracer of the tracer named "com.foo" and an ancestor of the tracer named "com.foo.bar". Each tracer name can be divided into one or more name components. Each name component identifies the name of the tracer at a particular level in the hierarchy. For example, the tracer named "com.foo.bar" has three name components, "com", "foo", and "bar". Tracer name components must be at least one character in length. This means that the tracer name "com.foo" is a legal name, whereas "com..foo" is not, as the middle name component of this name is zero-length.

The empty string, "", denotes the root tracer. The root tracer sits at the top of a tracer hierarchy and is the ancestor of all tracers in the hierarchy. The root tracer always exists.

All tracers may be assigned a TraceLevel. The Administrator uses the TraceMBean to change the trace level for a tracer. The effective trace level of a tracer is equal to its assigned trace level, or if the tracer has not been assigned a trace level then the effective trace level is equal to the trace level assigned to the nearest ancestor tracer. The root tracer always has an assigned trace level. The default trace level for all root tracers is TraceLevel.INFO.

All tracers are implicitly associated with a NotificationSource, an object that identifies the SLEE component or subsystem that the tracer was created for. For example, tracers created for an SBB via the SbbContext.getTracer(java.lang.String) method are associated with a notification source that identifies the SBB that the SbbContext was created for and the service that that SBB belongs to. A tracer's NotificationSource is included in any trace notifications generated by the TraceMBean on behalf of that tracer.

Tracers may be obtained by SBBs via the SbbContext.getTracer(java.lang.String) method. Tracers may be obtained by profiles via the ProfileContext.getTracer(java.lang.String) method. Tracers for a resource adaptor entity may be obtained via the ResourceAdaptorContext.getTracer(java.lang.String) method.

A Tracer is non-transactional. The effects of operations invoked on it occur regardless of the state or outcome of any enclosing transaction.

Since:

SLEE 1.1

See Also:

TraceMBean, TraceNotification

Method Summary

Methods

Modifier and Type	Method and Description
void	config(String message) Emit a trace message at the TraceLevel.CONFIG trace level.
void	config(String message, Throwable cause) Emit a trace message with a cause throwable at the TraceLevel.CONFIG trace level.
void	fine(String message) Emit a trace message at the TraceLevel.FINE trace level.
void	fine(String message, Throwable cause) Emit a trace message with a cause throwable at the TraceLevel.FINE trace level.
void	finer(String message) Emit a trace message at the TraceLevel.FINER trace level.
void	finer(String message, Throwable cause) Emit a trace message with a cause throwable at the TraceLevel.FINER trace level.
void	finest(String message) Emit a trace message at the TraceLevel.FINEST trace level.
void	finest(String message, Throwable cause) Emit a trace message with a cause throwable at the TraceLevel.FINEST trace level.
String	getParentTracerName() Get the name of this tracer's parent tracer.
TraceLevel	getTraceLevel() Get the current effective trace level for this tracer.
String	getTracerName() Get the tracer name for this tracer.
void	info(String message) Emit a trace message at the TraceLevel.INFO trace level.
void	info(String message, Throwable cause) Emit a trace message with a cause throwable at the TraceLevel.INFO trace level.
boolean	isConfigEnabled() Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.CONFIG trace level using this tracer.
boolean	isFineEnabled() Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.FINE trace level using this tracer.
boolean	isFinerEnabled() Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.FINER trace level using this tracer.
boolean	isFinestEnabled() Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.FINEST trace level using this tracer.
boolean	isInfoEnabled() Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.INFO trace level using this tracer.
boolean	isSevereEnabled() Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.SEVERE trace level using this tracer.
boolean	isTraceable(TraceLevel level) Determine if the current effective trace level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the specified trace level using this tracer.
boolean	isWarningEnabled() Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.WARNING trace level using this tracer.
void	severe(String message) Emit a trace message at the TraceLevel.SEVERE trace level.
void	severe(String message, Throwable cause) Emit a trace message with a cause throwable at the TraceLevel.SEVERE trace level.
void	trace(TraceLevel level, String message) Emit a trace message at the specified trace level.
void	trace(TraceLevel level, String message, Throwable cause) Emit a trace message with a cause throwable at the specified trace level.
void	warning(String message) Emit a trace message at the TraceLevel.WARNING trace level.
void	warning(String message, Throwable cause) Emit a trace message with a cause throwable at the TraceLevel.WARNING trace level.

Method Detail

getTracerName

String getTracerName()

Get the tracer name for this tracer.

Returns:

the tracer name.

This method is a non-transactional method.

getParentTracerName

String getParentTracerName()

Get the name of this tracer's parent tracer. For example, if getTracerName() returns , this method will return "com"

This method is a non-transactional method.

Returns:

the name of the this tracer's parent tracer, or null if this tracer is the root tracer.

getTraceLevel

TraceLevel getTraceLevel()
                         throws FacilityException

Get the current effective trace level for this tracer.

This method is a non-transactional method.

Returns:

the current effective trace level for this tracer.

Throws:

FacilityException - if the trace level could not be obtained due to a system-level failure.

severe

void severe(String message)
            throws NullPointerException,
                   FacilityException

Emit a trace message at the TraceLevel.SEVERE trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isSevereEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.SEVERE, message);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace message could not be emitted due to a system-level failure.

severe

void severe(String message,
          Throwable cause)
            throws NullPointerException,
                   FacilityException

Emit a trace message with a cause throwable at the TraceLevel.SEVERE trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isSevereEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.SEVERE, message, cause);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

isSevereEnabled

boolean isSevereEnabled()
                        throws FacilityException

Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.SEVERE trace level using this tracer.

This method is a convenience method equivalent to:

isTraceable(TraceLevel.SEVERE)

This method is a non-transactional method.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the TraceLevel.SEVERE level, false otherwise.

Throws:

FacilityException - if the result could not be obtained due to a system-level failure.

warning

void warning(String message)
             throws NullPointerException,
                    FacilityException

Emit a trace message at the TraceLevel.WARNING trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isWarningEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.WARNING, message);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

warning

void warning(String message,
           Throwable cause)
             throws NullPointerException,
                    FacilityException

Emit a trace message with a cause throwable at the TraceLevel.WARNING trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isWarningEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.WARNING, message, cause);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

isWarningEnabled

boolean isWarningEnabled()
                         throws FacilityException

Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.WARNING trace level using this tracer.

This method is a convenience method equivalent to:

isTraceable(TraceLevel.WARNING)

This method is a non-transactional method.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the TraceLevel.WARNING level, false otherwise.

Throws:

FacilityException - if the result could not be obtained due to a system-level failure.

info

void info(String message)
          throws NullPointerException,
                 FacilityException

Emit a trace message at the TraceLevel.INFO trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isInfoEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.INFO, message);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

info

void info(String message,
        Throwable cause)
          throws NullPointerException,
                 FacilityException

Emit a trace message with a cause throwable at the TraceLevel.INFO trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isInfoEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.INFO, message, cause);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

isInfoEnabled

boolean isInfoEnabled()
                      throws FacilityException

Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.INFO trace level using this tracer.

This method is a convenience method equivalent to:

isTraceable(TraceLevel.INFO)

This method is a non-transactional method.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the TraceLevel.INFO level, false otherwise.

Throws:

FacilityException - if the result could not be obtained due to a system-level failure.

config

void config(String message)
            throws NullPointerException,
                   FacilityException

Emit a trace message at the TraceLevel.CONFIG trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isConfigEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.CONFIG, message);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

config

void config(String message,
          Throwable cause)
            throws NullPointerException,
                   FacilityException

Emit a trace message with a cause throwable at the TraceLevel.CONFIG trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isConfigEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.CONFIG, message, cause);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

isConfigEnabled

boolean isConfigEnabled()
                        throws FacilityException

Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.CONFIG trace level using this tracer.

This method is a convenience method equivalent to:

isTraceable(TraceLevel.CONFIG)

This method is a non-transactional method.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the TraceLevel.CONFIG level, false otherwise.

Throws:

FacilityException - if the result could not be obtained due to a system-level failure.

fine

void fine(String message)
          throws NullPointerException,
                 FacilityException

Emit a trace message at the TraceLevel.FINE trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isFineEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.FINE, message);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

fine

void fine(String message,
        Throwable cause)
          throws NullPointerException,
                 FacilityException

Emit a trace message with a cause throwable at the TraceLevel.FINE trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isFineEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.FINE, message, cause);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

isFineEnabled

boolean isFineEnabled()
                      throws FacilityException

Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.FINE trace level using this tracer.

This method is a convenience method equivalent to:

isTraceable(TraceLevel.FINE)

This method is a non-transactional method.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the TraceLevel.FINE level, false otherwise.

Throws:

FacilityException - if the result could not be obtained due to a system-level failure.

finer

void finer(String message)
           throws NullPointerException,
                  FacilityException

Emit a trace message at the TraceLevel.FINER trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isFinerEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.FINER, message);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

finer

void finer(String message,
         Throwable cause)
           throws NullPointerException,
                  FacilityException

Emit a trace message with a cause throwable at the TraceLevel.FINER trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isFinerEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.FINER, message, cause);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

isFinerEnabled

boolean isFinerEnabled()
                       throws FacilityException

Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.FINER trace level using this tracer.

This method is a convenience method equivalent to:

isTraceable(TraceLevel.FINER)

This method is a non-transactional method.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the TraceLevel.FINER level, false otherwise.

Throws:

FacilityException - if the result could not be obtained due to a system-level failure.

finest

void finest(String message)
            throws NullPointerException,
                   FacilityException

Emit a trace message at the TraceLevel.FINEST trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isFinestEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.FINEST, message);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

finest

void finest(String message,
          Throwable cause)
            throws NullPointerException,
                   FacilityException

Emit a trace message with a cause throwable at the TraceLevel.FINEST trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isFinestEnabled() returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(TraceLevel.FINEST, message, cause);

This method is a non-transactional method.

Parameters:

message - the trace message.

Throws:

NullPointerException - if message is null.

FacilityException - if the trace could not be generated due to a system-level failure.

isFinestEnabled

boolean isFinestEnabled()
                        throws FacilityException

Determine if the current effective trace filter level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the TraceLevel.FINEST trace level using this tracer.

This method is a convenience method equivalent to:

isTraceable(TraceLevel.FINEST)

This method is a non-transactional method.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the TraceLevel.FINEST level, false otherwise.

Throws:

FacilityException - if the result could not be obtained due to a system-level failure.

isTraceable

boolean isTraceable(TraceLevel level)
                    throws NullPointerException,
                           FacilityException

Determine if the current effective trace level for this tracer is sufficient to allow a TraceNotification to be generated by the TraceMBean if a trace message was emitted at the specified trace level using this tracer.

An invocation of this method can be used as a guard around a trace invocation to avoid unnecessary computation of a trace message string that will ultimately be discarded.

This method is a convenience method equivalent to:

!getTraceLevel().isHigherLevel(level)

This method is a non-transactional method.

Parameters:

level - the trace level to test.

Returns:

true if the current effective trace filter level for this tracer allows a trace notification to be generated for a trace message emitted at the specified trace level, false otherwise.

Throws:

NullPointerException - if level is null.

FacilityException - if the result could not be obtained due to a system-level failure.

trace

void trace(TraceLevel level,
         String message)
           throws NullPointerException,
                  IllegalArgumentException,
                  FacilityException

Emit a trace message at the specified trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isTraceable(level) returns true, otherwise it has no effect and returns silently.

This method is equivalent to:

trace(level, message, null);

This method is a non-transactional method.

Parameters:

level - the trace level of the message.

message - the trace message.

Throws:

NullPointerException - if either level or message is null.

IllegalArgumentException - if level == TraceLevel.OFF.

FacilityException - if the trace could not be generated due to a system-level failure.

trace

void trace(TraceLevel level,
         String message,
         Throwable cause)
           throws NullPointerException,
                  IllegalArgumentException,
                  FacilityException

Emit a trace message with a cause throwable at the specified trace level. This method will only cause a TraceNotification to be generated by the TraceMBean if isTraceable(level) returns true, otherwise it has no effect and returns silently.

This method is a non-transactional method.

Parameters:

level - the trace level of the message.

message - the trace message.

cause - the reason (if any) this trace messages was generated. May be null.

Throws:

NullPointerException - if either level or message is null.

IllegalArgumentException - if level == TraceLevel.OFF.

FacilityException - if the trace could not be generated due to a system-level failure.