| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><HTML> | |
| <HEAD> | |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > | |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> | |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> | |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> | |
| <title>Running with tracing</title> | |
| </head> | |
| <BODY BGCOLOR="#ffffff"> | |
| <h2>Running with tracing</h2> | |
| <p>The platform provides a mechanism for tracking the activity of your plug-in at runtime | |
| without full debugging. It allows you to use tracing flags that will cause | |
| tracing information to be printed on the standard output (or Console view). These flags are defined in files named | |
| "<b>.options</b>" and have the following syntax:</p> | |
| <font color='#4444CC'><pre> <plug-in Id>/debug = true/false (master switch) | |
| <plug-in Id>/<tracing flag> = <value> | |
| </pre></font> | |
| <p>The first entry represents master switch for tracing your plug-in. If you | |
| call the method <b>isDebugging</b> in your plug-in class, it will | |
| return true if the value of this tracing variable is true. Other tracing flags | |
| are defined by you and their value can be obtained by using</p> | |
| <font color='#4444CC'><pre> Platform.getDebugOption(optionName); | |
| </pre></font> | |
| <p>Most of the platform plug-ins define tracing flags, particularly the platform | |
| core. For a new plug-in developer, the most interesting set of tracing flags | |
| are those related to class loading, because they can allow tracing of plug-in | |
| loading problems. </p> | |
| <p align="center"> | |
| <img border="0" src="images/launch-tracing.png" alt="Run-time workbench launcher - tracing" ></p> | |
| <h2>Example: Adding tracing support to your plug-in</h2> | |
| <p align="left">If you add tracing support to the plug-in under development, | |
| your plug-ins will appear in the list of plug-ins that support tracing.</p> | |
| <p>In order to allow other developers to control your plug-in's tracing flags, | |
| you need to make these options known. This is typically done by placing a <b>.options</b> | |
| file in your plug-in. The file lists all the supported flags as well as | |
| their default values. </p> | |
| <p>We will now define a template <b> .options</b> file with a | |
| few tracing flags for our new plug-in.</p> | |
| <p>Select the <b>com.example.xyz</b> project created earlier and create a new file | |
| .<b>options</b>. When | |
| the default text editor opens, add the following entries:</p> | |
| <font color='#4444CC'><pre> com.example.xyz/debug = true | |
| com.example.xyz/debug/flag = true | |
| com.example.xyz/debug/filter = * | |
| </pre></font> | |
| <p>When this file is saved, select <b>Run > Run...</b> to open the launch dialog. | |
| Our plug-in should now show up in the list. When selected, it should show the | |
| newly defined flags with their default values.</p> | |
| <p align="center"> | |
| <img border="0" src="images/xyz-tracing.png" alt="Run-time workbench launcher - tracing example" ></p> | |
| <p>Creating the <b>.options</b> file only defines the availability flags, | |
| allowing other plug-in developers to define the values of the tracing | |
| properties. You will still need to check the values of your tracing | |
| properties in your plug-in code using <b>Platform.getDebugOption()</b><b>.</b></p> | |
| </body> | |
| </html> |