Preparing Plug-ins for Tracing

This short topic explains which steps you have to follow to enable tracing configuration for a plug-in.

Relevant Classes

Package com.tssap.util.trace

TraceParticipant

You require this abstract class for linking up to the trace configuration using the extension point com.tssap.tools.ui.traceParticipant. The trace configuration is derived from a Properties object that is returned using the method getConfigurableElements(). This object describes mapping between location or category and the corresponding semantic names. This information is required for the trace configuration of the Eclipse Preferences page. Here, only the semantic names are displayed in the UI of the Preferences page.

ConvenienceTraceParticipant

This Convenience class inherits from TraceParticipant and implements the method getConfigurableElements(). The specifications for the trace configuration are received from a Properties file that is stored in the plug-in installation directory. This file has the standard name traceParticipant.properties because it is passed on as parameter in the method getPropFileName(). If you wish to have the Properties file stored under a different name or in a different directory within the plug-in project, you can simply overwrite the method getPropFileName() in your own Trace Participant class.

Relevant Classes

Each plug-in that implements a connection to the trace configuration requires its own Trace Participant class.

Task : Preparing a Plug-in for Trace Configuration

Solution

1. Create a Trace Participant class for your plug-in

In your plug-in project, create a new class that inherits from ConvenienceTraceParticipant. You generally do not need to implement this class further.

package com.sap.demo;

import com.tssap.util.trace.ConvenienceTraceParticipant;

public class MyTraceParticipant extends ConvenienceTraceParticipant {

}

2. Create a new property file

Create the Properties file and store it under the name traceParticipant.properties in the plug-in installation directory, that is, at the same level as the plugin.xml.

Example

In this Properities file, you first have the location com.sap.demo and the subordinate location com.sap.demo.MyClass listed. Only the assigned values (semantic names) are displayed in the UI of the trace configuration. The categories are specified in the same way, but here the slash (/) is used for the sequence in the tree.

com.sap.demo = My Tracer

com.sap.demo.MyClass = My class

/demoCategory = MyTest_Cat

/demoCategory/subCat = subCat

3. Register the new Trace Participant

If you have not already done so, add the plug-in com.tssap.util to your plugin.xml as the required plug-in.

...

  <requires>

      ...

<import plugin="com.tssap.util"/>

     ...

  </requires>

...

To register your new Trace Participant in plugin.xml, use the extension point com.tssap.tools.ui.traceParticipant. Assign the new Trace Participant (Step 1) of your plug-in as the traceParticipant class.

Example

...

<extension

point="com.tssap.tools.ui.traceParticipant">

<tracePaticipant

class="com.sap.demo.MyTraceParticipant">

</tracePaticipant>

</extension>

...

Result

To test the result, simply start the Runtime Workbench and display the UI for the trace configuration. For this purpose, choose the menu Window ® Preferences and then click the option Trace Configuration. The new entries that you have specified for the location or category in the Properites file are added to the entries already there.

FAQ

Q: Do I need to enable the trace configuration for each single plug-in?

A: Not necessarily. Often it makes sense to enable an entire group of plug-ins and thereby to create only one Properties file in a higher-level plug-in.

Q: Can I store the Properties file in any arbitrary plug-in folder?

A: Yes. However, for this you must overwrite the method getPropFileName() in your Trace Participant class by specifying the new path as parameter.

Q: What effect does it have if a plug-in with trace enabling is not available at runtime?

A: In the trace configuration of the Prefereces page, the corresponding location is marked with a red square as icon for the missing source.