Jackpot UI Specification
Author: Jan Rojcek
$Revision: 1.4 $
$Date: 2006/05/10 09:36:34 $
Table of Contents:
This use case covers three similar cases with the same usage scenario:
The user has an existing project and wants to
check its source code for
common errors and bad coding practices. Eventually the user wants to
transform the identified source code to the new code.
The user has an existing project or multiple projects and wants to
migrate its source code from one API to another API. This
includes cleaning up deprecated code, moving to newer, more efficient classes,
or moving to a completely different system architecture such as from ODBC to
JDBC.
The user has written a bunch of code (multiple classes in multiple packages in
multiple projects) and wants to
check, before committing the
changes, that the code the user has written contains no common errors
and bad coding practices.
Note: This use case would be
better covered with TODO list or similar UI.
Scenario:
- The user selects a project or multiple projects in Project window and
invokes Query and Refactor... in contextual menu which brings up the Query and Refactor dialog.
- In the dialog the user select a single query or set of queries
and clicks the Query button which performs the
query and opens the Query Results
window in the output window area.
- The user selects an item in the results window which brings up the Refactoring Preview window in the
editor area. The user interacts with the results window and preview window and
deselects refactorings she/he doesn't want to perform in the result window.
- When the user is satisfied with the selected set of refactorings in the
Query Results window, she/he just clicks
the Do Refactoring button in the results window which performs
the refactoring and closes the preview window and clears the results window.
The user has an existing project or multiple projects and wants to write and
test his own query and refactoring rule to find and correct something
in the project source code. Eventually the user wants to include the rule into
the set of rules that whole team of programmers should follow when writing
code.
Note: This use case covers writing the rules using the rule
language or using Java and the Jackpot API.
Rule Language Scenario:
- The user opens up the Refactoring
Manager dialog from the Tools menu and clicks the
New button which brings up the New Query
dialog.
- In the New Query dialog the user specifies the name of
the query and refactoring and clicks the Create button which
closes the dialog and adds a new query into the list of queries. It also opens
up the new query file in the editor.
- The user closes the manager dialog with the close button.
- In the editor the user writes the rule code and uses the Run | Run
File action or Query and Refactor... action in the
main menu which opens the Query and
Refactor dialog.
Java and Jackpot API Scenario:
- The user creates a new module...
Figure: Source menu
| Refactor |
------------
Query and Refactor "My Project"...
-------------------------
Rename...
Extract Method...
Change Method Parameters...
...
Figure: Tools menu
| Tools |
---------
...
-------------------------
Refactoring Manager
Java Platform Manager
Library Manager
Server Manager
NetBeans Platform Manager
-------------------------
Module Manager
Update Center
-------------------------
Options
Components:
- Query and Refactor - opens the Query and Refactor dialog.
- Refactoring Manager - opens the Refactoring Manager dialog.
Figure: Contextual menu on project node
...
Find...
-------------------------
Query and Refactor...
CVS >
Tools >
-------------------------
Properties
Components:
- Query and Refactor - opens the Query and Refactor dialog with the
selected project context.
The Query and Refactor dialog performs the query part of the query
and refactoring.
Note: We should still consider having
the refactoring with preview as a next step in this dialog (wizard). This
would require to also change the refactoring to follow such UI.
Figure: Query and Refactor invoked from contextual menu with 3 projects selected
+---------------------------------------------------------------------------------+
| Query and Refactor - My Project |
+---------------------------------------------------------------------------------+
| |
| Query Using: |
| (o) Query Set: |_Coding Style__________________________________________v_| |
| ( ) Single Query: |_Unused Local Variables________________________________v_| |
| [ Manage Queries... ] |
| |
| |
| [[ Query ]] [ Cancel ] |
+---------------------------------------------------------------------------------+
Figure: Query and Refactor with single query selected
+---------------------------------------------------------------------------------+
| Query and Refactor - My Project |
+---------------------------------------------------------------------------------+
| |
| Query Using: |
| ( ) Query Set: |_Coding Style__________________________________________v_| |
| (o) Single Query: |_Unused Local Variables________________________________v_| |
| [ Manage Queries... ] |
| Options: |
| [x] Ignore Constant Variables |
| |
| |
| [[ Query ]] [ Cancel ] |
+---------------------------------------------------------------------------------+
Components:
- Manage Queries button opens up the the Refactoring Manager dialog.
- Query button closes the dialog and opens up the Query Results window.
Figure: Refactoring Manager dialog
+-------------------------------------------------------------------------------+
| Refactoring Manager |
+-------------------------------------------------------------------------------+
| |
| Query Set: |_Default__________________________v_| [ Duplicate... ] [ Delete ] |
| |
| Queries: |
| |_________Search For____________|__________Refactor___________| |
| | [x] Bad Finally Blocks | None | [ Import... ] |
| | [x] Unused Variables | None | [ Export... ] |
| | [x] Statistics??? | ??? | |
| | [x]/Conditionals//////////////|/Convert to If Statements////| [ Delete ] |
| | [x] Missing Deprecated Anno...| Add Annotations | |
| | [x] Missing Override Annota...| Add Annotations | [ Move Up ] |
| | [x] Beanize??? | | [ Move Down ] |
| | [x] Missing Copyright | Add Copyright | |
| | [x] Clean-up??? | ??? | |
| | [x] SwingUtilities Methods | ??? | |
| | [x] Field Access | Convert to Method Access | |
| | [x] Public Field Access | Encapsulate Field | |
| | [x] Method Access | Convert to Field Access | |
| | [x] Simple If Statements | Convert to Conditionals | |
| | [x] Unnecessary Casts | Remove Casts | |
| | [x] Complex Boolean Express...| Simplify Expressions | |
| | [x] Complex Loops | Simplify Loops | |
| | [x] StringTokenizer | Convert to Scanner | |
| | [x] Tail Merge??? | ??? | |
| | | | |
| +-------------------------------------------------------------+ |
| |
| _____________ _________ |
| / Description \/ Options \ |
| | \----------------------------------------------+ |
| | Search for conditional expressions and convert them to if | |
| | statements: | |
| | | |
| | if a return b; else return c => return a ? b : c; | |
| | if (a) ret = b; else ret = c => ret = a ? b : c; | |
| | if (a) b=c; else if (a2) b = d => b = a ? c : a2 ? d; | |
| | ... | |
| +-------------------------------------------------------------+ |
| |
| [ New Query... ] [ Edit Query ] [[ Close ]] |
+-------------------------------------------------------------------------------+
Figure: New Query Set dialog
+--------------------------------------------------------------+
| New Query Set |
+--------------------------------------------------------------+
| |
| Query Set Name: |__________________________________________| |
| |
| [[ OK ]] [ Cancel ] |
+--------------------------------------------------------------+
Figure: New Query dialog
+--------------------------------------------------------------+
| New Query |
+--------------------------------------------------------------+
| |
| Query Name: |_New Query______________________________| |
| Refactoring Name: |_New Refactoring________________________| |
| |
| Note: This will create a new query using Jackpot rule file. |
| You can also define complex queries and refactorings by |
| writing a new NetBeans module using Jackpot APIs. |
| See Jackpot Tutorial. |
| |
| |
| [[ Create ]] [ Cancel ] |
+--------------------------------------------------------------+
Components:
- Queries defined by jackpot classes are gray in the list. If such query is
selected the Export button, Delete button and Edit Query button are
disabled.
- Duplicate... button opens up up the New Query Set dialog.
- Delete shows up a confirmation dialog and deletes the query set.
- Import... button opens the file chooser dialog titled Import
Query. The file type combo says Jackpot rule files
(*.rules). Only folders and rule files are visible in the file
chooser. The default location is user home. The buttons are
Import and Cancel.
- Export... button opens the file chooser dialog titled Export
Query. The file type combo says Jackpot rule files
(*.rules). Only folders and rule files are visible in the file
chooser. The default location is user home and the default file name is the
display name of the exported query, e.g. Public Field
Access.rules. The buttons are Import and
Cancel.
- New Query... button opens the New Query dialog.
- Create button in the New Query dialog closes the New Query and Refactoring
Manager dialogs and opens up the query file in the editor.
- Edit Query button opens the selected item in editor. It doesn't close
the dialog.
- Options tab is disabled if there's no options for selected query.
The Query Results window shows all occurrences of selected query.
Figure: Query Result window with single query
+---------------------------------------------------------------------------------+
| Query Results - Public Field Access - My Application |
+---------------------------------------------------------------------------------+
| Public Field Access => Encapsulate Field |
| - [x] MyClass.foo (com.mycompany.myapp) |
| [x] public foo -> private foo |
| [x] add getFoo() |
| [x] add setFoo() |
| [x] change Mumble.method(): foo += 5 -> setFoo(getFoo() + 5) |
| + [x] MyClass.myvar2 (com.mycompany.myapp) |
| + [x] MySuperClass.someField (com.mycompany.myapp.store) |
| |
| |
| |
| |
| |
| |
|---------------------------------------------------------------------------------|
| [ Do Refactoring ] |
+---------------------------------------------------------------------------------+
Figure: Query Result window with multiple queries
+---------------------------------------------------------------------------------+
| Query Results - Coding Style - My Application |
+---------------------------------------------------------------------------------+
| Public Field Access => Encapsulate Field |
| - [x] MyClass.foo (com.mycompany.myapp) |
| [x] public foo -> private foo |
| [x] add getFoo() |
| [x] add setFoo() |
| [x] change Mumble.method(): foo += 5 -> setFoo(getFoo() + 5) |
| + [x] MyClass.myvar2 (com.mycompany.myapp) |
| + [x] MySuperClass.someField (com.mycompany.myapp.store) |
| Unused Local Variables => Remove Variable |
| + [x] MyClass.myvar (com.mycompany.myapp) |
| + [x] MyClass.myvar2 (com.mycompany.myapp) |
| + [x] MySuperClass.someField (com.mycompany.myapp.store) |
| Conditionals => Convert to If Statement |
| + [x] Class.method() (com.mycompany.myapp) |
| + [x] Class.otherMethod() (com.mycompany.myapp) |
| + [x] SuperClass.someMethod() (com.mycompany.myapp) |
| Missing @Deprecated Annotations => Add Annotation |
| + [x] HelloClass.mymethod() (com.mycompany.myapp.store) |
| |
| |
|---------------------------------------------------------------------------------|
| [ Do Refactoring ] |
+---------------------------------------------------------------------------------+
Components:
- Selecting an item in the results window opens up the Refactoring Preview window.
- Do Refactoring button performs the selected refactoring.
The Refactoring Preview window opens up in the editor and contains the diff
component showing the intended refactoring changes.
Figure: Refactoring preview window
+-----------------------------------------------------+
| My Application [Refactoring Preview - Coding Style] |
+---------------------------------------------------------------------------------+
| *MyClass.java (com.mycompany.myapp)* |
| | |
| public Foo foo; | private Foo foo; |
| | |
| ... |
| | |
| | public void setFoo(Foo foo) { |
| | this.foo = foo; |
| | } |
| | |
| ... |
| | |
| | public Foo getFoo() { |
| | return foo; |
| | } |
| | |
|---------------------------------------------------------------------------------|
| *Mumble.java (com.mycompany.myapp)* |
| | |
| private void method() { | private void method() { |
| foo += 5; | myclass.setFoo(myclass.getFoo() + 5); |
| } | } |
| | |
+---------------------------------------------------------------------------------+
Figure: Query Editor window
+----------------------------+
| Simple If Statements.rules |
+---------------------------------------------------------------------------------+
| /** |
| * Convert if statements to conditional expressions. |
| */ |
| if ($a) return $b; else return $c => return $a ? $b : $c; |
| if ($a) $ret = $b; else $ret = $c => $ret = $a ? $b : $c; |
| if ($a) $b=$c; else if ($a2) $b = $d => $b = $a ? $c : $a2 ? $d : $b; |
| $a ? ($T)$b : ($T)$c => ($T)($a ? $b : $c); |
| { $p$; $T $v; if($a) $v = $b; else $v = $c; $q$; } => { $p$; $T $v = $a ? $b... |
| |
| |
| |
| |
| |
| |
| |
| |
|---------------------------------------------------------------------------------|
| Sample Code to Convert: Converted Code: |
|---------------------------------------+-----------------------------------------|
| if (a < 10) | return a < 10 ? a : 10; |
| return a; | |
| else | |
| return 10; | |
| | |
+---------------------------------------------------------------------------------+
