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:

  1. Creating an empty Probekit source file
  2. Creating the Probekit source file contents
  3. Checking the probe

Creating an empty Probekit source file

You are going to create the Probekit source file in a project of its own. (You can also create probes in the same project as your application, but you have to convert the project to a Probekit project in order build probes.)

  1. Create a new Java project to hold the probe:
    1. From the Software Development Platform menu bar, click File > New > Project. The New Project dialog box opens.
    2. Expand the Java entry, then select Java Project and click Next. The New Java Project dialog box opens.
    3. In the Project name field, type RandomNumbersProbe and click Finish. An entry for RandomNumbersProbe is added in the Package Explorer view.
  2. Convert the project into a Probekit project:
    1. In the Package Explorer view, right-click the RandomNumbersProbe project that you just created, then click New > Other. The New dialog box opens.
    2. Check Show All Wizards, and then expand the Profiling and Logging entry.
    3. Select Convert Java Projects to Probekit Projects, and click Next.
    4. 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.
    5. Make sure that only the RandomNumbersProbe project is checked, and then click Finish.
  3. Create a new Probekit source file in the RandomNumbersProbe project:
    1. In the Package Explorer view, right-click RandomNumbersProbe, and then click New > File. The New File dialog box opens.
    2. Select RandomNumbersProbe to make it the parent folder.
    3. In the File Name field, type RandomNumbersProbe.probe (the extension .probe is required), then click Finish. An entry for RandomNumbersProbe.probe is added to the Package Explorer view. The Probekit editor and Problems view open.

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 "Build Automatically" 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 Probekit source file contents

You will now use the Probekit editor to create the probe.

Each probe definition includes a fragment, which defines the probe's logic. The probe that you are going to create contains a single Java code fragment of the type "entry." 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 this probe, whenever a method is entered, the "entry" fragment will print out the class and method name.

To achieve this, you need write source code for the fragment, and also to define two pieces of data, class name and method name, that the fragment must be able to access.

Note: Probekit supports other types of fragments in addition to "entry" fragments. For example, you can also write fragments that run when specified methods exit, or when a specified method handles an exception. Refer to the help system for detailed information.

You will be writing the probe in such a way as to apply to all classes and methods. When you run it, however, you will narrow its scope by filtering out system classes as part of the launch procedure.

To create your probe:

  1. At the lower edge of the Probekit editor, click the Probes tab. (Entries in the General page are optional; you can use them for record-keeping.)
  2. Click Add Probe. A Probe entry is added in the tree pane on the left side of the editor.
  3. Right-click the newly created Probe entry and click New > Fragment. A Fragment entry is added in the tree pane under the Probe entry. By default, fragments are created as "entry" fragments. (Note that entry is also the selection in the Fragment Type field in the editing pane on the right side of the Probekit editor.)
  4. Double-click the tab of the Probekit editor view to enlarge the editor so that you can see the entire editing pane. (Double-clicking the tab again restores the view to its original size.)
  5. Create a variable to hold the first of the data items that you want to define, the class name:
    1. In the editing pane under "Data Items," click Add. A default data item of type "className" is added.
    2. Click Edit.
    3. In the Edit Data Item dialog box, in the Name field, type cname as the variable name, then click OK.
  6. Create a variable to hold the second data item, the method name:
    1. Click Add again, then click Edit to edit the newly added data item.
    2. For Data Type, select methodName from the list.
    3. In the Name field, type mname as the variable name, then click OK.
  7. In the Java Code area, type the following line of code:
    System.out.println("[Enter method " + cname + "." + mname + "]");
  8. 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:

That's it: you've created your first probe.

Now you are ready to begin Exercise 1.3: Applying your probe.

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.