javax.slee.management
Interface TraceMBean

public interface TraceMBean

The TraceMBean interface defines the management interface for the SLEE tracing subsystem. Using the TraceMBean, a management client may get or set the trace filter levels used to control whether or not the Trace MBean generates TraceNotifications for trace messages emitted by SLEE components such as SBBs, profiles, and resource adaptor entities.

The JMX Object Name of a TraceMBean object is specified by the OBJECT_NAME constant. Alternatively, the Object Name can be obtained by a management client via the SleeManagementMBean.getTraceMBean() method.

Trace Filter Levels
A trace filter level may be assigned to each tracer used by a particular NotificationSource. Different trace filter levels may be assigned for a tracer with the same name but associated with different notification sources. For example, for the tracer named "com.foo", it is possible to set the trace filter level the tracer to TraceLevel.FINEST for some SBB in a service and TraceLevel.INFO for another SBB in the same service, as each SBB is a unique notification source.

When a message is emitted to a tracer, the effective trace filter level is used to determine whether or not the Trace MBean generates a TraceNotification. The effective trace filter level of a tracer is equal to the trace filter level assigned to the tracer for the notification source in which the Tracer object was created. If a trace filter level has not been assigned to that tracer, the effective trace filter level is inherited from its nearest ancestor in the tracer hierarchy that has an assigned trace filter level. The root tracer of each possible notification source always has a trace filter level assigned to it, which initially defaults to TraceLevel.INFO. A SLEE implementation should (but is not required to) persist any trace filter levels set during normal operation, so that trace filter levels can be restored upon a complete server restart.

As an example, assume the following management operations (only) have been invoked on the Trace MBean:

SbbNotification sbb = ...
setTraceLevel(sbb, "", TraceLevel.INFO);
setTraceLevel(sbb, "com.foo", TraceLevel.FINEST);

The following management operations would return effective trace levels as indicated:

getTraceLevel(sbb, "") == TraceLevel.INFO
getTraceLevel(sbb, "com") == TraceLevel.INFO
getTraceLevel(sbb, "com.foo") == TraceLevel.FINEST
getTraceLevel(sbb, "com.foo.bar") == TraceLevel.FINEST


When a trace message is emitted to a tracer, if the trace level of the trace message is greater than or equal to the effective trace filter level of the tracer for the notification source it was created for, a TraceNotification will be generated by the Trace MBean and delivered to any notification listeners. Otherwise the trace message is silently discarded by the SLEE.

Notifications
Since a TraceMBean object can emit trace notifications, it is required that the TraceMBean object implement the javax.management.NotificationBroadcaster interface.

Note: In SLEE 1.0 a Trace MBean emitted only one type of notification, defined by TRACE_NOTIFICATION_TYPE. As of SLEE 1.1, a TraceMBean object may emit trace notifications of different types, depending on the notification source of the tracer used to emit the trace message. The SLEE-defined classes that implement NotificationSource each specify the type of trace notification that is generated for the notification source.

Field Summary

static java.lang.String	OBJECT_NAME The JMX Object Name string of the SLEE Trace MBean, equal to the string "javax.slee.management:name=Trace".
static java.lang.String	TRACE_NOTIFICATION_TYPE Deprecated. Different notification types may be generated by the Trace MBean depending on where the trace message was emitted. The SLEE-defined classes that implement NotificationSource each specify a particular trace notification type for the notification source.

Method Summary

Level	getTraceLevel(ComponentID id) Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the tracing subsystem in SLEE 1.1. It has been replaced with getTraceLevel(NotificationSource, String).
TraceLevel	getTraceLevel(NotificationSource notificationSource, java.lang.String tracerName) Get the effective trace filter level of the specified tracer for the specified notification source.
java.lang.String[]	getTracersSet(NotificationSource notificationSource) Get the names of the tracers for which a trace filter level has been assigned for the specified notification source.
java.lang.String[]	getTracersUsed(NotificationSource notificationSource) Get the names of the tracers that have been requested by the specified notification source.
void	setTraceLevel(ComponentID id, Level traceLevel) Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the tracing subsystem in SLEE 1.1. It has been replaced with setTraceLevel(NotificationSource, String, TraceLevel).
void	setTraceLevel(NotificationSource notificationSource, java.lang.String tracerName, TraceLevel level) Set the trace filter level of the specified tracer for the specified notification source to the specified trace level.
void	unsetTraceLevel(NotificationSource notificationSource, java.lang.String tracerName) Unset the trace filter level of the specified tracer for the specified notification source.

Field Detail

OBJECT_NAME

static final java.lang.String OBJECT_NAME

The JMX Object Name string of the SLEE Trace MBean, equal to the string "javax.slee.management:name=Trace".

Since:

SLEE 1.1

See Also:

Constant Field Values

TRACE_NOTIFICATION_TYPE

static final java.lang.String TRACE_NOTIFICATION_TYPE

Deprecated. Different notification types may be generated by the Trace MBean depending on where the trace message was emitted. The SLEE-defined classes that implement NotificationSource each specify a particular trace notification type for the notification source.

The notification type of Trace notifications emitted by this MBean. The notification type is equal to the string "javax.slee.management.trace".

See Also:

Constant Field Values

Method Detail

setTraceLevel

void setTraceLevel(ComponentID id,
                   Level traceLevel)
                   throws java.lang.NullPointerException,
                          UnrecognizedComponentException,
                          ManagementException

Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the tracing subsystem in SLEE 1.1. It has been replaced with setTraceLevel(NotificationSource, String, TraceLevel).

Set the trace filter level for a particular component. The TraceMBean only generates trace notifications if the trace level of a trace message generated by a component is equal to or greater than the trace filter level set for that component.

The default trace filter level for a component is Level.OFF, ie. trace notifications are never generated for the component unless the trace filter level is explicitly set to a different level.

Parameters:

id - the identifier of the component.

traceLevel - the new trace filter level for the component.

Throws:

java.lang.NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognizable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

ManagementException - if the trace level could not be set due to a system-level failure.

getTraceLevel

Level getTraceLevel(ComponentID id)
                    throws java.lang.NullPointerException,
                           UnrecognizedComponentException,
                           ManagementException

Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the tracing subsystem in SLEE 1.1. It has been replaced with getTraceLevel(NotificationSource, String).

Get the trace filter level for a particular component.

The default trace filter level for a component is Level.OFF, ie. trace notifications are never generated for the component unless the trace filter level is explicitly set to a different level.

Parameters:

id - the identifier of the component.

Returns:

the trace filter level for the component.

Throws:

java.lang.NullPointerException - if id is null.

UnrecognizedComponentException - if id is not a recognizable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

ManagementException - if the trace level could not be set due to a system-level failure.

getTracersUsed

java.lang.String[] getTracersUsed(NotificationSource notificationSource)
                                  throws java.lang.NullPointerException,
                                         UnrecognizedNotificationSourceException,
                                         ManagementException

Get the names of the tracers that have been requested by the specified notification source.

Parameters:

notificationSource - the notification source.

Returns:

an array of tracer names corresponding to the tracers that have been requested by the specified notification source.

Throws:

java.lang.NullPointerException - if notificationSource is null.

UnrecognizedNotificationSourceException - if notificationSource does not identify a notification source recognizable by the SLEE.

ManagementException - if the tracer names could not be obtained due to a system-level failure.

Since:

SLEE 1.1

setTraceLevel

void setTraceLevel(NotificationSource notificationSource,
                   java.lang.String tracerName,
                   TraceLevel level)
                   throws java.lang.NullPointerException,
                          UnrecognizedNotificationSourceException,
                          InvalidArgumentException,
                          ManagementException

Set the trace filter level of the specified tracer for the specified notification source to the specified trace level.

Parameters:

notificationSource - the notification source.

tracerName - the name of the tracer for which the trace level should be assigned. The empty string denotes the root tracer.

level - the trace filter level to be assigned to the tracer.

Throws:

java.lang.NullPointerException - if any argument is null.

UnrecognizedNotificationSourceException - if notificationSource does not identify a notification source recognizable by the SLEE.

InvalidArgumentException - if tracerName is not a valid tracer name.

ManagementException - if the trace filter level could not be set due to a system-level failure.

Since:

SLEE 1.1

unsetTraceLevel

void unsetTraceLevel(NotificationSource notificationSource,
                     java.lang.String tracerName)
                     throws java.lang.NullPointerException,
                            UnrecognizedNotificationSourceException,
                            InvalidArgumentException,
                            ManagementException

Unset the trace filter level of the specified tracer for the specified notification source. This method removes any trace filter level previously assigned to the tracer so that the effective trace filter level of that tracer is subsequently obtained from the tracer's parent tracer.

This method has no effect, and returns without error, if no trace filter level is currently assigned to the specified tracer.

The trace filter level for the root tracer (identified by the empty string) cannot be unset.

Parameters:

notificationSource - the notification source.

tracerName - the name of the tracer for which the trace level should be unset.

Throws:

java.lang.NullPointerException - if any argument is null.

UnrecognizedNotificationSourceException - if notificationSource does not identify a notification source recognizable by the SLEE.

InvalidArgumentException - if tracerName is not a valid tracer name, or is the empty string (denoting the root tracer).

ManagementException - if the trace filter level could not be unset due to a system-level failure.

Since:

SLEE 1.1

getTracersSet

java.lang.String[] getTracersSet(NotificationSource notificationSource)
                                 throws java.lang.NullPointerException,
                                        UnrecognizedNotificationSourceException,
                                        ManagementException

Get the names of the tracers for which a trace filter level has been assigned for the specified notification source. This method returns the list of tracer names for which trace filter levels have been assigned for the notification source using the setTraceLevel method, and for which the trace filter level has not yet been unset using the unsetTraceLevel method.

Parameters:

notificationSource - the notification source.

Throws:

java.lang.NullPointerException - if notificationSource is null.

UnrecognizedNotificationSourceException - if notificationSource does not identify a notification source recognizable by the SLEE.

ManagementException - if the tracer names could not be obtained due to a system-level failure.

Since:

SLEE 1.1

getTraceLevel

TraceLevel getTraceLevel(NotificationSource notificationSource,
                         java.lang.String tracerName)
                         throws java.lang.NullPointerException,
                                InvalidArgumentException,
                                UnrecognizedNotificationSourceException,
                                ManagementException

Get the effective trace filter level of the specified tracer for the specified notification source. Note that the returned trace level may not be directly assigned to the specified tracer, but may have been obtained from the tracer's nearest ancestor that has a trace filter level assigned.

The default trace filter level for the root tracer for all tracers is TraceLevel.INFO. Thus the default effective trace filter level for all tracers obtained by a notification source is also TraceLevel.INFO.

Parameters:

notificationSource - the notification source.

tracerName - the name of the tracer for which the effective trace level should be obtained. The empty string denotes the root tracer.

Returns:

the current effective trace filter level for the tracer.

Throws:

java.lang.NullPointerException - if any argument is null.

UnrecognizedNotificationSourceException - if notificationSource does not identify a notification source recognizable by the SLEE.

InvalidArgumentException - if tracerName is not a valid tracer name.

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

Since:

SLEE 1.1