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.
