Lesson 1: Begin Instance Fields with Underscore

This rule will report a violation when instance fields do not begin with an underscore.

Designing the Rule Pattern

Creating the Parent Node

Whenever you create a rule, the first thing you need to do to is right-click the node that you want to be your rule's main subject, then select Create Rule from the shortcut menu. To start composing this rule, open Declarations> Variables, right-click the Field node, then choose Create Rule from the shortcut menu.

After you choose Create Rule, you will see the following parent rule node in the right pane of the GUI:

We now have the basic building block for a rule about fields.

Adding Further Qualifications to the Parent Rule Node

To specify that we want this rule to check instance (non-static) fields, first add the IsStatic property by right-clicking the Field rule node and choosing IsStatic from the shortcut menu that opens. This says to check if the field is static. This is not what we want to check for, so we will need to modify this node.

To have Jtest check if the field is not static, right-click the IsStatic box and choose Toggle. This will change this rule condition to say "if an instance variable is present."

To specify that this rule will be about naming conventions, right-click the Field rule node and choose Name from the shortcut menu that opens.

A rule node with the content Name: -none- will now be attached to your parent rule node.

To continue developing the rule, right-click the Name rule node, then choose Modify from the shortcut menu.

The Modify String window will then open.

In the Regexp field of the Modify String window, specify what value Jtest should look for in the name of the instance variable.

If you want Jtest to report an error if a certain value is not present in the code, (as we do in our example), enter the value that you want to require the presence of, then check the Negate check box. This tells Jtest to report an error if the specified value is not present.
If you want Jtest to report an error if a certain value is present in the code, enter the value that you do not want to appear in your code, then leave the Negate check box empty. This tells Jtest to report an error if the specified value is present.
In our example, we want the Name value to begin with an underscore. Thus, we would enter

^_.
in the Regexp field, and check the Negate check box. (The "^" indicates the beginning of an expression and the "." matches any single character).

After you have typed this value and checked the check box, click OK.

Specifying an Error Message

Finally, we need to specify what text Jtest should print when this rule is violated. The first step in doing this is right-clicking the parent rule node (here, the Field rule node), then choosing Create Output from the shortcut menu.This action will invoke the following Customize Output window:

In the Customize Output window, enter the message that you want Jtest to deliver when this rule is violated. In this example, you might enter "Invalid field name: $name". When this message is reported by Jtest, $name will be replaced by the actual name of the field.

Click OK.

Your rule should now look like this:

Your rule now tells Jtest to report the specified error message when an instance variable's name does not begin with an underscore. Your rule is now complete. After you customize this rule's properties and save it, Jtest will be able to enforce it.

Customizing Rule Properties

Rule properties can be customized via the Rule Properties panel. To access this panel, choose Rule> Properties.

You will then see the Rule Properties panel.

This panel lets you determine the rule's properties. In the CodeWizard tab, enter...

a rule ID: the unique ID you want to assign to this rule. If you want Jtest to organize your custom rules into categories, use the following format:

category.id
For example, you could use "Example.IFM"
a header: the name you want Jtest to assign to this rule. For this example, you could enter

Instance fields should start with the character "_"

Next, choose the rule's severity (the severity category in which Jtest will classify the rule). This rule should be categorized as a Violation.

Finally, click the Info tab, and enter the name of the rule's author (your name and/or development group) and a description of the rule. (This description will be displayed when users choose View Rule Description within Jtest).

When you have entered all of these values, click OK to close this panel.

For more information on any of the fields in the Rule Properties panel, see the Rule Properties Panel page.

Saving and Enabling Your Rule

Before you begin composing another rule, or before you exit the program, you will want to save your rule (Jtest only enforces rules that have been saved).

To save your rule, choose Rule> Save or Rule> Save As. This command will invoke a file chooser in which you can specify the rule's filename and path. Be sure to give each rule you save a .rule extension. If you do not use this exact extension, Jtest will not load your rules properly. Also, be sure to save your rules within the default directory (<Jtest installation directory>/jrules). If a rule is not contained in this directory, Jtest will not enforce it.

After you save your rule, exit RuleWizard. To enable your rule:

Click Global in either of Jtest's UIs.
In the Global Test Parameters window, go to Static Analysis> Rules> User Defined Rules, then right-click User Defined Rules. A shortcut menu will open.
Choose Reload Rules from the shortcut menu that opens.

Your rule will then be enabled.

Enforcing Your Rule Automatically

If you look at the Global Test Parameters tree's Static Analysis> Rules> User Defined Rules branch, you will see that Jtest automatically added and enabled the rule you just created.

This rule will now be included in the set of rules Jtest applies to your class or classes during static analysis.

To see how this rule is used, test the Point class (located in <Jtest installation directory>/examples/static/userdef). Two errors will be reported for this test.