jrefactory

Creating custom actions.

ProjectViewer allows other plugin developers too interact with the file trees by creating custom actions to be executed on the nodes. Actions can be added to the tree's context menu or to the viewer's toolbar. It's recommended to extend the context menu, since there's only so much useful space in the toolbar for new actions.

Creating a new action is very simple:

• Create a new class that extends {@link projectviewer.action.Action Action}.
• Implement the {@link projectviewer.action.Action#actionPerformed(ActionEvent) actionPerformed()} method to execute the desired operations.
• Register the action in the context menu ({@link projectviewer.vpt.VPTContextMenu#registerAction(Action) registerAction()}) or in the toolbar ({@link projectviewer.ProjectViewer#registerAction(Action) registerAction()}) by calling the appropriate method.

The menu item show in the context menu is provided by the {@link projectviewer.action.Action#getMenuItem() getMenuItem()} of the Action class. Subclasses are welcome to override this method to provide other kinds of menu items (a sub-menu, for example). For the toolbar button, the {@link projectviewer.action.Action#getButton() getButton()} method is used.

Before showing the menu item in the context menu, ProjectViewer will call the {@link projectviewer.action.Action#prepareForNode(VPTNode) prepareForNode()} method in all actions registered in the context menu. This allows each action to decide if it should be shown for the given node and what message to show, for example. For the toolbar buttons, this method is never called, so the toolbar buttons should be able to be executed regardless of the current tree selection. If your action depends on a certain kind of node, add it to the context menu, and not to the toolbar. If you want to add it to the toolbar, check for the node type in your actionPerformed() implementation.

Another important thing to notice in the prepareForNode() method is that the actions should check is the node is of a certain type, and not if the node is not of a certain type. For example, use "node.isFile()" and not "!node.isDirectory()". This ensures that the action will not do anything wrong if a different node type is added in the future to PV, or if another plugin adds a new node type to PV.

It's important to notice that the instance given to the registerAction methods is not the instance used by the viewer instances. Those instances are used as prototypes, and the viewers use {@link projectviewer.action.Action#clone() clone()} to get instances for the specific viewer. After the cloning, the {@link projectviewer.action.Action#setViewer(ProjectViewer) setViewer()} method is called, so the actions have a reference to the viewers where they are being used. This also means that you should not use the constructor of your Action implementation to instantiate GUI components. Instantiations of GUI components should be done lazily in the getMenuItem() or getButton() methods. The default implementation already does this, so you should only worry about this if you are overriding one of these methods.

• Refactoring is the base class for refactoring.
• TransformAST is the base class for making a transformation on a syntax tree.
• ComplexTransform combines a number of TransformASTs together to update a single file.
• RefactoringException is thrown when the requested refactoring cannot be performed.
• AddImportTransform is a TransformAST that adds an import statement to the file
• RemoveImportTransform is a TransformAST that removes an import statement from a file

How to create a new refactoring

This portion of the document describes how to create a new refactoring, or at least the methodology that was used to create the existing refactorings.

The first step is to create a set of source files to test on. This file contains the "clean" version of the file before the refactoring was applied. Then I hand edited the file so that it was the correct result. Then applied the pretty printer to the edited file. (If more than one file is updated by a refactoring, this process is repeated for each file.)

The second step is to create a unit test. To do this, I extended org.acm.seguin.junit.DirSourceTestCase. This takes all the features of the TestCase from junit and adds in the specific directories. Root is the working directory, clean contains the unmodified files, and check contains the correct files. The unit test:

1. Copies the files from the clean directory to the working directory
2. Applies the refactoring
3. Compares the file in the working directory to the correct file
4. Deletes the file in the working directory

To get the unit test to compile, I create a refactoring class. I call the refactoring class XXXRefactoring, and it extends org.acm.seguin.refactor.Refactoring. The refactoring goes into the appropriate package. At the moment, the kinds of refactoring are:

• org.acm.seguin.refactor.type - renaming and moving classes, adding child or parent classes, removing classes
• org.acm.seguin.refactor.field - renaming and moving fields
• org.acm.seguin.refactor.method - renaming and moving methods

I quickly create the empty methods so that the refactoring is not abstract, and then everything should compile. I compile, and run the unit tests to see that the junit test fails because the files do not match. (Other types of failures are caused by the unit test being incorrect - so now that is debugged.)

Next I create a number of TransformASTs that perform some unit transformation on the parse tree. I've used these to add or remove a node in the parse tree or replace a name everywhere it occurs in the source tree.

Sometimes a TransformAST hands it's work off to a Visitor object. The org.acm.seguin.parser.ChildrenVisitor is a good one to choose as a base class for this visitor. It already provides the ability to traverse the entire tree. Then all I have to do is overload the specific visit methods for the nodes I'm concerned about.

To learn more about what exactly the source tree looks like, look at the java1_1.jjt file that is included in the code.jar file.

Now we have a bunch of TransformAST objects which might call visitors to do their work. How do these get combined together to update a single file? I would then create a ComplexTransform and add to it each TransformAST object that is necessary to update that file. Create an instance of the ComplexTransform with the getComplexTransform() method of the Refactoring object. (This is done to support undoing the refactoring.)

If the effect of a refactoring requires that perhaps a large number of files be modified, then I use a SummaryVisitor to traverse all the source files that are loaded into memory. A good visitor to extend is the org.acm.seguin.summary.TraversalVisitor. It traverses the summary file.

To learn more about the Summary objects, look at the org.acm.seguin.summary package. The Summary objects store the metadata for all the source files that are loaded. One thing to note about the FileSummary objects is that if they have a file that is equal to null, then the FileSummary and associated types are from the JDK or a 3rd party library. These types cannot be updated by the refactoring tool.

By this point we have a Refactoring object. It applies a ComplexTransform to a single file or uses a TraversalVisitor to apply the ComplexTransform to a series of files. The ComplexTransform applies a number of TransformAST objects to update a single parse tree.

Once the unit test passes, you are done!

This package also contains a number of different visitors that traverse the entire tree of source files, since type based operations have the possibility of changing all the source files in the system.

Beneath that are TransformAST objects which perform a single unit operation such as renaming a type. The actual work isusually done by the associated visitor object.

There is no support yet for redoing actions.

Undoing a particular change to a specific file are stored by renaming the current file with an extension, .java.# where # is the number of times the file has been changed by the refactoring tool. Let's call this method of storing the previous incarnations of a file an indexed file.

An undo action then has a number of indexed files associated with them. It also has a description of the refactoring so that a user interface component can display a list of refactorings to undo.

The undo stack then holds all the undo action objects. It uses a singleton pattern to insure that only a single instance of the undo stack is present in the editor at a time.

This package stores summaries as well as the loaders for these structures.

Subpackages store procedures that search the summary tree or find specific information about the tree.

To add more items to the menu that pops up on the class diagrams, edit UMLPopupMenu. This menu has been broken into a number of methods each generating a particular submenu. The ActionListener that is invoked are stored either in org.acm.seguin.uml.refactor if it is a refactoring, or org.acm.seguin.ide.common.

The reason to place it in ide.common is that we want to isolate changes that are specific to a particular release of an editor. This makes it easier to add the feature to other editors.