Exercise 1.2: Creating your first probe
Before you begin, you must complete Exercise 1.1: Importing the required resource.
The probe that you are going to create reports whenever a method in your program is entered.
Creating a probe involves three main tasks:
- Creating an empty Probekit source file
- Creating the source file contents
- Checking the probe
Creating an empty Probekit file
We're going to create the Probekit file in a project of its own, though you can also create probes in the same project as your application.
- Create a new Java project to hold the probe:
- From the Software Development Platform menu bar, select File > New > Project... The New Project dialog box opens.
- Select Java Project and click Next. The New Java Project dialog box opens.
- In the Project name field, type RandomNumbersProbe and click Finish. An entry for RandomNumbersProbe is added in the Package Explorer view.
- Convert the project into a Probekit project:
- In the Package Explorer view, right-click the RandomNumbersProbe project that you just created, and select New > Other... The New dialog box opens.
- Check Show All Wizards, and then expand the Profiling and Logging entry.
- Select Convert Java Projects to Probekit Projects, and click Next.
- If the Confirm Enablement dialog box opens, click Always enable capabilities and don't ask me again, and then click OK. The Convert Java Projects to Probekit Projects dialog box opens.
- Make sure that only the RandomNumbersProbe project is checked, and then click Finish.
- Create a new Probekit source file in the RandomNumbersProbe project:
- In the Package Explorer view, right-click RandomNumbersProbe.
- Select New > File. The New File dialog box opens.
- Select RandomNumbersProbe to make it the parent folder.
- In the File Name field, type RandomNumbersProbe.probe, then click Finish. An entry for RandomNumbersProbe.probe is added to the Package Explorer view. The Probekit editor and Problems view open. The editor displays the newly created file.
You now have an empty Probekit source file in its own project. Since the file is in a Probekit project, and since you have enabled auto-build in your workspace, the probe compiler has tried to compile the source file. The Problems view reports an error because an empty file is not a valid Probekit source file.
Creating the source file contents
You will now use the Probekit editor to create the probe elements that make up a probe.
Probekit source files are tree-structured. There is a Probekit element at the top. You need to create a Probe element under the Probekit element, and a new Fragment element under that. Then you need to indicate that this Fragment element will access two pieces of data: the class name and method name. Finally, you need to write the Java code fragment itself.
The probe that we want to create consists of a single "entry" Java code fragment. An "entry" fragment is a fragment that is triggered at the method-entry time of specified methods in the program that you are investigating. In our probe, whenever a method is entered, the "entry" fragment will print out the class and method name. As written, our probe will apply to all classes and methods; when we deploy it, however, we will narrow its scope by filtering out system classes as part of the launch procedure.
Note: Probekit supports other types of fragments in addition to "entry" fragments. For example, you can also write fragments that are executed when specified methods exit, or when a specified method handles an exception. Refer to the help system for detailed information.
To create the elements for your probe:
- In the Probekit editor, right-click the Probekit element and choose New > Probe. A Probe element is added to the tree.
- Right-click the newly created Probe element and select New > Fragment. A Fragment element is added under the Probe element. By default, fragments are created as "entry" fragments. (Note that entry is also the selection in the Fragment Type field on the right side of the Probekit editor.)
- Create a variable to hold the class name:
- Right-click the Fragment entry element and select New > Data.
- On the right side of the Probekit editor, make sure that className is selected as the Data Type.
- In the Name field, type cname as the variable name.
- Create the variable to hold the method name:
- Right-click the Fragment entry element and select New > Data.
- Select methodName from the Data Type drop-down list.
- In the Name field, type mname as the variable name.
- Type the Java code you want to run:
- Click the Fragment entry element.
- In the Java Code area, type the following line of code:
System.out.println("[Enter method " + cname + "." + mname + "]");
- From the menu bar, select File > Save. The probe compiler automatically compiles the probe from its source code.
Checking the probe
When you save your probe, the probe compiler reports errors in the Problems view. Check the Problems view to see if anything went wrong. If there are errors, correct them in the Probe editor and save the probe again.
Two kinds of errors can be reported in the Problems view:
- One kind of error is a structural error in the Probekit source file. For example, a Probe element cannot contain two fragments of the same type. The Problems view reports this kind of error in the Resource column as errors in the probe source file.
- The other kind of error is in the Java source code component of a probe fragment. Because of the way Probekit is structured internally, these errors are actually reported against a different file, a Probekit-generated file that in this case would be called RandomNumbersProbe_probe.java. If you double-click on the error in the Problems view, the generated Java source file opens. You could even fix the problem there, but you shouldn't: any changes you make here will be overwritten the next time the probe compiler generates the file from the probe source. Instead, you should examine the generated Java file to determine which fragment the error appears in, and then fix the problem in that fragment using the Probekit editor.
That's it: you've created your first probe.
Now you are ready to begin Exercise 1.3: Applying your probe.