The Trace Dip provides debugging and diagnostic information when it is applied to a dippable bean instance. When a dippable bean is deployed and dipped with the trace dip, the dippable bean can log messages when entering or leaving methods or log property change and event information. You can use the customizer to tailor the options you want to trace. The output for the trace dip is logged to the MsgDisp utility, a window that captures the information. The MsgDisp logging function can run locally or remotely to provide text-based distributed debugging. For additional information, see "Using MsgDisp".
The Trace Dip can trace the following:
Methods | All methods of the dipped bean can log information that provides:
A Dip.VetoableMethodListener implementation logs information when a method is called and never vetoes the method. A Dip.MethodCallListener implementation is used to log information when exiting a method. |
Properties | The Dip.VetoableChangeListener implementation intercepts property changes to log bean property values. This listener never vetoes the method. The PropertyChangeListener implementation intercepts and logs bean property values. |
Events | The Dip.VetoableEventListener and Dip.EventFireListener implementations log event-related information generated by the bean. The VetoableEventListener never vetoes the method. All events generated by the bean are logged. Events can be traced only if they use the fireEventMethod pattern. For additional information, see "The Dipping Framework". |
The Trace Dip Customizer allows the user to specify whether to trace method, properties, events, or all three. The customizer allows the user to specify where the MsgDispServer is running by entering a network host name. The default host name is the local machine.
The Trace Dip requests a high priority. This high priority allows the Trace Dip to intercept events, method calls, or property changes fired before other dip listeners. After a constrained event, method, or property is vetoed, the dip framework does not fire events to the remaining listeners that are registered. The vetoable listeners log a message stating that they received an event, method call, or property change.
If the event, method call, or property change is vetoed by another dip's event listener, a message is logged in the trace dip event listeners recoverFromMethodVeto() method or in the recoverFromEventVeto() method called by the dip framework. This message states that the event never happened because it was vetoed. This logic produces a more complete trace of what occurred during bean deployment. If a dippable bean is dipped and has a higher priority or has the same priority as the Trace Dip, the trace dip event listener may not be called first. In this case, there is no way to trace that an event, method call, or property change was vetoed.
For additional information on the priority of a dip, see Dip.priority in the Bean Extender API Reference.
When applying the TraceDip to certain AWT components (such as a Button) while the component is running on the Assembly Surface (e.g., in the Layout view), and while the TraceDip is logging method calls to stdout, and the Log view is open on the Assembly Surface capturing stdout output, deadlock may result when manipulating the component (such as pushing the Button) in the Layout view. This occurs with a Button, for example, because when the Button is pushed, the AWT must update the display of the Button, which requires it to make method calls on the Button, which triggers the TraceDip to log the method calls. If these log entries require the display of the Assembly Surface's Log view to be updated, deadlock occurs. The deadlock can be avoided by either closing the Log view while manipulating the Button, or configuring the TraceDip to log method calls to a MsgDispServer (running on the same machine or a different machine) rather than to stdout.
Any terminal exceptions that occur in the Trace Dip are written to standard error. No exceptions are thrown out of the dip. If a terminal condition occurs, then all Trace Dip methods become non-operational.
The message log can contain a variety of messages. This section contains the types of messages and their syntax. The following variables are used in the message log.
fromHost | The host machine where the log message originated. |
dippableBeanClassName | The bean dipped in the Dip Trace. |
dippableBeanMethodWrapped | The bean method wrapped with the trace function. |
dippableBeanProperty | The property contained in the modified bean. |
eventInformation | The event generated by the dippable bean. |
MethodWrappedArguments | The arguments passed to the bean method wrapped with the Trace Dip. |
NewPropertyValue | The new property value. |
Old PropertyValue | The old property value. |
The following output message types use the previously defined variables.
Bound Event |
fromHost:TraceDip:handleEventFire | dippableBean=dippableBeanClassName | event=eventInformation |
Constrained Event |
fromHost:TraceDip:handleVetoableEvent | dippableBean=dippableBeanClassName | event=eventInformation |
Constrained Event Vetoed |
fromHost:TraceDip:recoverFromEvent | dippableBean=dippableBeanClassName | event=eventInformation |
Bound Method |
fromHost:TraceDip:handleMethodCall | dippableBean=dippableBeanClassName | MethodWrapped=dippableBeanMethodWrapped | args=MethodWrappedArguments |
Constrained Method |
fromHost:TraceDip:handleVetoableMethod | dippableBean=dippableBeanClassName | MethodWrapped=dippableBeanMethodWrapped | args=MethodWrappedArguments |
Constrained Method Vetoed |
fromHost:TraceDip:recoverFromMethod | dippableBean=dippableBeanClassName | MethodWrapped=dippableBeanMethodWrapped | args=MethodWrappedArguments |
Bound Property Change |
fromHost:TraceDip:propertyChange | Property=dippableBeanProperty | NewValue=NewPropertyValue | OldValue=OldPropertyValue |
Constrained Property Change |
fromHost:TraceDip:propertyChange | Property=dippableBeanProperty | NewValue=NewPropertyValue | OldValue=OldPropertyValue |
The MsgDisp utility provides functions to log or print messages to a scrolling window. The MsgDisp utility consists of the MsgDispServer and the MsgDispClient. You can save the contents of the window from the server.
Only one MsgDispServer at a time can run on any given computer. The MsgDispServer can run on one computer while the Trace Dip runs on another. The Trace Dip Customizer allows the user to specify the MsgDispServer location.
If the MsgDispServer is not running when the trace dip logs messages, then the output is written to standard output. Computers running MsgDispServer and Trace Dip must have a TCP/IP stack to log messages.
To start the MsgDispServer, enter the following command at a command prompt:
java com.ibm.beans.samples.dips.trace.MsgDispServer