javax.slee.management
Class TraceNotification

java.lang.Object
  java.util.EventObject
      javax.management.Notification
          javax.slee.management.TraceNotification

All Implemented Interfaces:

java.io.Serializable, VendorExtensions

public final class TraceNotification
extends javax.management.Notification
implements VendorExtensions

Notifications of this type are emitted by a TraceMBean. Trace notifications for a particular notification source are enabled by setting the appropriate trace level for the notification source using the methods on the TraceMBean interface. If a trace message is generated in the SLEE, typically using a Tracer object, at a trace level lower than the trace level set for the notification source in the Trace MBean, the message is discarded by the SLEE and no trace notification is generated.

Trace notifications contain a NotificationSource object that can be used to obtain more information about the object that caused the trace notification to be generated. The type of a trace notification can be used to infer the type of the notification source object contained in the notification:

• if Notification.getType() == SbbNotification.TRACE_NOTIFICATION_TYPE then the type of the notification source object is SbbNotification.
• if Notification.getType() == ResourceAdaptorEntityNotification.TRACE_NOTIFICATION_TYPE then the type of the notification source object is ResourceAdaptorEntityNotification.
• if Notification.getType() == ProfileTableNotification.TRACE_NOTIFICATION_TYPE then the type of the notification source object is ProfileTableNotification.
• if Notification.getType() == SubsystemNotification.TRACE_NOTIFICATION_TYPE then the type of the notification source object is SubsystemNotification.

As of SLEE 1.1, serialization of this class has been modified to take into account cause Throwable objects that may not be deserializable client-side due to classloader issues. For example, if the cause of a trace message is an object of a custom exception class included in the deployable unit of a component, a generic client may not have that class available in its classpath or be able to load it via Java's remote class loading mechanisms (eg. the codebase URL could be a file:// URL on a different host that cannot be resolved on the client host). Serialization of a TraceNotification object containing a cause now includes the stack trace of that cause in the serialization stream. If the cause Throwable cannot be later deserialized with the TraceNotification object, a generic java.lang.Exception with a message containing the original stack trace is returned as the trace's cause instead.

See Also:

Serialized Form

Field Summary

Fields inherited from class javax.management.Notification

source

Constructor Summary

TraceNotification(java.lang.String type, TraceMBean traceMBean, NotificationSource notificationSource, java.lang.String tracerName, TraceLevel traceLevel, java.lang.String message, java.lang.Throwable cause, long sequenceNumber, long timestamp)
Create a TraceNotification to notify listeners of a trace message.

TraceNotification(TraceMBean traceMBean, java.lang.String messageType, java.lang.Object messageSource, Level traceLevel, java.lang.String message, java.lang.Throwable cause, long sequenceNumber, long timestamp)
Deprecated. Trace notifications have been expanded with new attributes to take advantage of the new features provided by the SLEE specification. The TraceNotification(String, TraceMBean, NotificationSource, String, javax.slee.facilities.TraceLevel, String, Throwable, long, long) constructor should be used instead of this constructor.

Method Summary

static void	disableVendorDataDeserialization() Disable the deserialization of vendor-specific data for objects of this class.
static void	disableVendorDataSerialization() Disable the serialization of vendor-specific data for objects of this class.
static void	enableVendorDataDeserialization() Enable the deserialization of vendor-specific data for objects of this class.
static void	enableVendorDataSerialization() Enable the serialization of vendor-specific data for objects of this class.
boolean	equals(java.lang.Object obj) Compare this notification for equality with another object.
java.lang.Throwable	getCause() Get the cause (if any) for this trace notification.
Level	getLevel() Deprecated. Replaced with getTraceLevel() as trace and alarm levels have been split into different classes.
java.lang.Object	getMessageSource() Deprecated. Replaced with getNotificationSource().
java.lang.String	getMessageType() Deprecated. Replaced with getTracerName().
NotificationSource	getNotificationSource() Get the object that identifies the component or subsystem in the SLEE that caused this trace notification to be generated.
TraceLevel	getTraceLevel() Get the trace level of the trace message.
java.lang.String	getTracerName() Get the name of the tracer to which the trace message was emitted.
java.lang.Object	getVendorData() Get the vendor-specific data.
int	hashCode() Get a hash code value for this notification.
void	setVendorData(java.lang.Object vendorData) Set the vendor-specific data.
java.lang.String	toString() Get a string representation for this notification.

Methods inherited from class javax.management.Notification

getMessage, getSequenceNumber, getTimeStamp, getType, getUserData, setSequenceNumber, setSource, setTimeStamp, setUserData

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TraceNotification

public TraceNotification(TraceMBean traceMBean,
                         java.lang.String messageType,
                         java.lang.Object messageSource,
                         Level traceLevel,
                         java.lang.String message,
                         java.lang.Throwable cause,
                         long sequenceNumber,
                         long timestamp)
                  throws java.lang.NullPointerException,
                         java.lang.IllegalArgumentException

Deprecated. Trace notifications have been expanded with new attributes to take advantage of the new features provided by the SLEE specification. The TraceNotification(String, TraceMBean, NotificationSource, String, javax.slee.facilities.TraceLevel, String, Throwable, long, long) constructor should be used instead of this constructor.

Create a TraceNotification to notify listeners of a trace message.

Parameters:

traceMBean - the TraceMBean object that is emitting this notification.

messageType - the type of the trace message being generated and correspondingly the sub-type of the notification.

messageSource - a component identifier that identifies the component that generated the trace message, for example an SbbID.

traceLevel - the trace level.

message - the trace message.

cause - an optional cause for the trace message.

sequenceNumber - the notification sequence number within the source TraceMBean object.

timestamp - the time (in ms since January 1, 1970 UTC) that the trace message was generated.

Throws:

java.lang.NullPointerException - if notificationSource, messageType, traceLevel, or message is null.

java.lang.IllegalArgumentException - if traceLevel == Level.OFF.

TraceNotification

public TraceNotification(java.lang.String type,
                         TraceMBean traceMBean,
                         NotificationSource notificationSource,
                         java.lang.String tracerName,
                         TraceLevel traceLevel,
                         java.lang.String message,
                         java.lang.Throwable cause,
                         long sequenceNumber,
                         long timestamp)
                  throws java.lang.NullPointerException,
                         java.lang.IllegalArgumentException

Create a TraceNotification to notify listeners of a trace message.

Parameters:

type - the JMX type of the notification. The type of the notification is typically obtained from the NotificationSource parameter when this notification object is created, and can be used by notification listeners to infer the type of the NotificationSource and hence obtain further information about the source of the notification.

traceMBean - the TraceMBean object that is emitting this notification.

notificationSource - the component or subsystem in the SLEE that caused this notification to be generated.

tracerName - the name of the tracer to which the trace message was emitted.

traceLevel - the trace level.

message - the trace message.

cause - an optional cause for the trace message.

sequenceNumber - the notification sequence number within the source TraceMBean object.

timestamp - the time (in ms since January 1, 1970 UTC) that the trace message was emitted.

Throws:

java.lang.NullPointerException - if type, traceMBean, notificationSource, tracerName, traceLevel, or message is null.

java.lang.IllegalArgumentException - if traceLevel == TraceLevel.OFF.

Since:

SLEE 1.1

Method Detail

getNotificationSource

public NotificationSource getNotificationSource()

Get the object that identifies the component or subsystem in the SLEE that caused this trace notification to be generated.

Returns:

the notification source. Returns null for SLEE 1.0-compliant notifications.

Since:

SLEE 1.1

getMessageType

public java.lang.String getMessageType()

Deprecated. Replaced with getTracerName().

Get the type of the trace message.

Returns:

the trace message type. Returns the value of getTracerName() for SLEE 1.1-compliant notifications.

getTracerName

public java.lang.String getTracerName()

Get the name of the tracer to which the trace message was emitted.

Returns:

the name of the tracer to which the trace message was emitted. Returns the same value as getMessageType() for SLEE 1.0-compliant notifications.

Since:

SLEE 1.1

getMessageSource

public java.lang.Object getMessageSource()

Deprecated. Replaced with getNotificationSource().

Get the object that identifies the source of the trace message.

Returns:

the trace message source. Returns the value of getNotificationSource() for SLEE 1.1-compliant notifications.

getLevel

public Level getLevel()

Deprecated. Replaced with getTraceLevel() as trace and alarm levels have been split into different classes.

Get the trace level of the trace message.

Returns:

the trace level. Returns the Level equivalent of the traceLevel attribute for SLEE 1.1-compliant notifications.

getTraceLevel

public TraceLevel getTraceLevel()

Get the trace level of the trace message.

Returns:

the trace level. Returns null for SLEE 1.0-compliant notifications.

Since:

SLEE 1.1

getCause

public java.lang.Throwable getCause()

Get the cause (if any) for this trace notification.

Returns:

the cause for this trace notification, or null if there wasn't a cause.

enableVendorDataSerialization

public static void enableVendorDataSerialization()

Enable the serialization of vendor-specific data for objects of this class. This method is typically used by a SLEE implementation that wants to export vendor-specific data with objects of this class to management clients.

By default, any vendor-specific data included in an object of this class will not be included in the serialization stream when the object is serialized. Invoking this method changes this behavior so that vendor-specific data is included in the serialization stream when an object of this class is serialized.

This method should only be invoked if the vendor-specific data is serializable via standard Java serialization means.

Since:

SLEE 1.1

See Also:

disableVendorDataSerialization(), setVendorData(java.lang.Object)

disableVendorDataSerialization

public static void disableVendorDataSerialization()

Disable the serialization of vendor-specific data for objects of this class.

If the serialization of vendor-specific data for objects of this class has been enabled via the enableVendorDataSerialization() method, this method disables that behavior again.

Since:

SLEE 1.1

enableVendorDataDeserialization

public static void enableVendorDataDeserialization()

Enable the deserialization of vendor-specific data for objects of this class. This method is typically used by a management client that wants to obtain any vendor-specific data included in the serialization stream of objects of this class.

By default, any vendor-specific data included in the serialization stream of objects of this class is discarded upon deserialization. Invoking this method changes that behavior so that the vendor-specific data is also deserialized when an object of this class is deserialized. A management client that enables the deserialization of vendor-specific data must ensure that any necessary classes required to deserialize that data is available in the relevant classloader.

Since:

SLEE 1.1

See Also:

disableVendorDataDeserialization(), getVendorData()

disableVendorDataDeserialization

public static void disableVendorDataDeserialization()

Disable the deserialization of vendor-specific data for objects of this class.

If the deserialization of vendor-specific data for objects of this class has been enabled via the enableVendorDataDeserialization() method, this method disables that behavior again.

Since:

SLEE 1.1

setVendorData

public void setVendorData(java.lang.Object vendorData)

Set the vendor-specific data.

Specified by:

setVendorData in interface VendorExtensions

Parameters:

vendorData - the vendor-specific data.

Since:

SLEE 1.1

getVendorData

public java.lang.Object getVendorData()

Get the vendor-specific data.

Specified by:

getVendorData in interface VendorExtensions

Returns:

the vendor-specific data.

Since:

SLEE 1.1

equals

public boolean equals(java.lang.Object obj)

Compare this notification for equality with another object.

For backwards compatibility, this method performs either a SLEE 1.0-based comparison or a SLEE 1.1-based comparison based on the state of this notification object. If this notification contains a non-null message source reference, a SLEE 1.0-based comparison is performed, using the SLEE 1.0 trace levels. Otherwise, a SLEE 1.1-based comparison is performed using the SLEE 1.1 trace levels.

The SLEE 1.0-based comparison considers two notifications to be equal if obj is an instance of this class and the message type, message source, trace level and message attributes of obj are the same as the corresponding attributes of this.

The SLEE 1.1-based comparison considers two notifications to be equal if obj if an instance of this class and the tracer name, notification source, trace level and message attributes obj are the same as the corresponding attributes of this.

Note that a SLEE 1.0-compliant trace notification can never be equal to a SLEE 1.1-compliant trace notification.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare this with.

Returns:

true if obj is equal to this according to the rules specified above, false otherwise.

hashCode

public int hashCode()

Get a hash code value for this notification. The hash code is the hash code of the notification's message.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code for this notification.

toString

public java.lang.String toString()

Get a string representation for this notification.

Overrides:

toString in class javax.management.Notification

Returns:

a string representation for this notification.