Excalibur Instrument - InstrumentablesInstrumentablesThe Instrumentable interface is required to be able to register a component with an InstrumentManager. The interface makes it possible for the InstrumentManager to query the component about what Instruments and child Instrumentables is making available. The interface provides four methods. The first two, setInstrumentableName and getInstrumentableName are used to get and set the name of the Instrumentable. This name is similar to a category name in logger frameworks. The name is required by the InstrumentManager to be able to provide clients with a way to request and access instrumentation output. The name should not include any periods as they are used as separators in a hierarchy of Instrumentables and their Instruments. The name of top level Instrumentable is usually set by the object which creates the component. Usually this is a container. If the creating object is not aware of the Instrument API then it is possible that setInstrumentableName will never be called. Components should be able to function properly under this condition. In the case of child Instrumentables, it is the responsibility of the parent to call setInstrumentableName. The third and fourth methods, getInstruments and getChildInstrumentables, are each called once by an InstrumentManager to query the Instrumentable for a list of the Instruments and child Instrumentables that is making available. Implementing the Instrumentable interface directly requires a little bit of work, but is necessary in cases where the parent class can not be controlled. In most situations, it is possible to extend one of the two helper classes provided with the API, AbstractInstrumentable and AbstractLogEnabledInstrumentable. Either of these classes provide methods to add Instruments and Child Instrumentables to the lists to be published. All of the above methods are handled behind the scenes. The second helper class is available for classes also wish to extend the AbstractLogEnabled class provided with Framework. (If this class is used, then Instrument requires that the avalon-framework.jar file be included in the classpath.) An example of the AbstractLogEnabledInstrumentable helper class is not included as its usage is identical to AbstractInstrumentable. |