Jackpot Tutorial

This is not a tutorial in the traditional sense, but rather a few short "experiments" to introduce you to Jackpot and how it can be used.

First Experiment: The Refactoring Manager

The Refactoring Manager dialog displays the installed queries and their associated refactorings.  Run the "Tools->Refactoring Manager" menu item to bring up this dialog.  It looks complicated, but is easy to decipher.  Each line in the main table describes a query.  The "Search For" column displays what pattern each query is looking for, while the "Refactoring" column displays what operation will be run to correct the problem.  Click on different queries, and the description panel will display more information regarding them.  A few queries also have options; click on the Options tab when it is enabled to see what options that query has.

Above the Queries table is the "Query Set" section.  A query set is a group of queries which can be executed as a single command; this allows you to batch related queries together as you wish.  The initial query set is called "Default"; click on that combo box, select "Effective Java Items", and notice that the left-hand column of checkboxes in the queries table changed.  Add or remove queries from a query set by clicking the query's checkbox.  To create a new query set, click the "Duplicate" button, give the query set a name, and then click the checkboxes to select which queries belong in that set.

Second Experiment: Queries

Queries are Jackpot commands which explore a model of your project's source code, reports found patterns and other facts, and optionally refactors the found patterns.  A simple query is "Unused variables", which finds variable declarations which are not referenced.  If you look at its entry in the Refactoring Manager dialog, you'll see that it doesn't have an associated refactoring; it may someday, but now it just reports its results without refactoring.  Now select a project in the Projects window, and run "Refactor->Query and Refactor..." to display the Jackpot query exection dialog.  Click on the "Single Query" radio button, and select "Unused variables" query from the single query combo box.  A results report is displayed if any are found; double-click any row to see the source code declaring that variable.

Third Experiment: Refactoring

Any query in the Refactoring Manager which has an entry in the Refactoring column can automatically refactor the pattern it found.  Try running the "Unnecessary casts" query by selecting a project, invoking the "Query and Refactor...", and selecting that query.  If any cast expressions are found which can be safely eliminated, they are displayed in the results window.  Double-click any of these rows to see a diff window with the source code before and after the query's refactoring would be done.  If you don't want any of these refactorings to be made, uncheck the checkbox next to each one.  Hit "Do Refactoring" to run the checked refactorings, which will then update the affected source files.  Try some other queries.  You will find that some queries may not return any results because no code was found that matched the patterns for which the queries were searching.  Since most queries are looking for potentially bad code patterns, no results are good news.

Fourth Experiment: Rule Files

Many Jackpot queries can be written using its rule language.  To look at the rule files of the built-in commands, display the Refactoring Manager dialog and select each query; those queries that are implemented with rule files will have the "Edit Query..." button enabled.  Click that button to see how the query is written.

To write your own Jackpot transformation, we will clone the "Unnecessary casts" query.  First, click the "New Query..." button in the Refactoring Manager.  In the New Query dialog, specify "Redundant casts" for the Query Name, "Eliminate cast" for the Refactoring name, add a longer description if you want, and hit the "OK" button.  A Java-like editor pane is opened with your new rule file.  Enter the following rule that removes the unnecessary casts:
    ($T)$a => $a :: $a instanceof $T;
This rule has two "meta-variables" in it, $T and $a, which are wildcards for Java code.  The choice of 'T' and 'a' is arbitrary; in this case $T stands for a Java type reference, while $a can match any expression.  The "=>" is the transformation query while "::" is used to specify any restrictions on a match.  This rule can be read as "Remove any cast from any expression if and only if the expression is already the type of the cast."  More information on the rule language is here.

To run this rule file against your project, select a project and invoke "Refactor->Query and Refactor...", select your new query and hit the Query button.  If there are any unnecessary casts in your project, they will be listed in a results window.  Select on any result to see a diff of the before and after code your rule file transformed.  To apply the refactorings, uncheck the results you don't want changed and hit "Do Refactoring".

Last Experiment:  Source Formatting Options

You probably won't agree with Jackpot's default options for pretty-printing Java source code, because very few developers can agree on such an issue.  To set these options, invoke "Tools->Options" and select the Jackpot icon.  Click on each tab to see what choices it offers, and try changing the options to see what effect they have on the example code (the example display will be improved).  These options are saved as Java preferences, and so will be used regardless of what build of NetBeans is run or what userdir is specified.

You can also adjust the colors used when editing Jackpot rules files, in the "Fonts & Colors" options panel.  In the Syntax tab, select the "Jackpot Rules" language to display and change the color options.