Xrefactory for jEdit

General

 Xrefactory is a refactoring development environment for Java. Its functions can be accessed via the 'Plugins->Xrefactory' submenu of the main menu bar. Optionally the most frequent functions can be bind on shortcuts. Xrefactory can be customized via standard jEdit customization dialog.

Quick start

To quickly start working with Xrefactory just invoke any of its functions. You will be asked for creation of a project. Then Xrefactory will create its database for the project and is ready for use.

Projects

Xrefactory is project based, you will need to create and maintain description of your projects. Particularity of Xrefactory projects is possibility of autodetection. Xrefactory detects the 'active project' from the path of currently edited file. Each project contains list of 'autodetection directories' specifying when the project should be triggered 'active'. Only one project at the time can be active. In consequence 'autodetection directories' have to be distinct for all projects. Information about the selected 'active project' is displayed after each browsing action in the bottom information line of the editor.

NOTE: Project autodetection directories are (in general) not the same as directories containing project files. Project files can contains common libraries used in many projects, while project detection directory should be the directory which is project specific, i.e. directory containing project specific files not shared with other projects.

Tags

The main object Xrefactory works with are 'Tags'. Each project has its Tags stored in files specified by user. Tags contain informations about your project sources. In particular, informations about all symbols, their linking properties, definition place(s) and all usages. Tags can be split into any number of files. The number of tag files is specified by user. Larger number makes browsing faster, but makes creation and update of Tags slower. The maintenance of tags is in major part automatic. However it may happens that tags will become inconsistent. Then it is recommended to re-create tags manually.

Xref task

Xrefactory cooperates with an external task 'xref', if you feel that the task has run into an inconsistent state, you can invoke the 'Kill xref task' function.

Completion

 Completion is implemented with the function 'Complete' and usually is bind to 'Control Space' hot-key. Completion tries to complete identifier before the caret by contextually appropriate strings. Xrefactory is recognizing around 15 different context among them, completion of class attributes, classes, methods parameters, variable definitions, etc. When several possibilities are available the completion dialog appears.

Completion Dialog

Each line of the dialog contains following informations: the identifier to insert, the inheritance level and the class where proposed symbol is defined, and the full definition of the symbol. Symbol can be selected using standard motion keys. Following special keys are available:
<return>- close dialog and insert completion.
<space>- inspect definition (or javadoc) of the symbol.
<escape>- return to invocation place and close dialog.
<alt><escape>- close dialog.
When completing a type name, fully qualified names of classes from jar archives are proposed. When selecting such name, an additional dialog appears proposing you to add new import clause.

Browser

 Xrefactory browser allows to resolve any symbol in source file, inspect its definition and all usages. Following four basic functions are available for browsing and it is usual to bind them to hot-keys:

When browsing a symbol, you first need to fix it by moving the caret on an occurrence of the symbol and invoking 'Browse Symbol from Editor and Goto Definition' function. In the case of success the caret is moved to the definition of the symbol. This is because inspecting definition is the most usual browsing function and it is performed together with the resolution. In case you are trying to browse a virtual method and the unique definition can not be determined by static analysis, the Browser Dialog is opened for manual resolution. After successful resolution you can inspect all usages of the symbol using 'Previous' and 'Next Reference' functions.

Browser allows simultaneous browsing of multiple symbols. For example, let's imagine you are browsing all usages of a variable 'variable' and you see that it is used as a parameter of a method 'method'. So, you wish to find the definition of the 'method'. In this situation simply put caret on the 'method' and invoke 'Push Symbol and Goto Definition' once more time. You will be moved to the definition of the 'method' and you can inspect its code. After this you wish to continue browsing remaining usages of the 'variable'. But when you try to use 'Previous' and 'Next Reference' you see that those functions are now inspecting all usages of the 'method' (not 'variable' as you wish). In this situation you first need to invoke the function 'Backward'. After this, the 'Previous' and 'Next Reference' functions works with usages of the 'variable'.

As illustrated by this example, Xrefactory browser is based on browser stack. Newly browsed symbols are pushed on the top of the stack by the function 'Browse Symbol from Editor and Goto Definition'. Functions 'Previous' and 'Next Reference' are inspecting previous and next usage of the symbol placed on the top of the stack. Function 'Backward' is removing one element from the top of the stack.

It is possible to push back an element which was poped from the stack by error. This is done with the function 'Browser - Forward'. This function is particularly useful when using visualization of the browser stack in the Browser Dialog.

Another way how to push references onto browser stack is the function: 'Browser - Browse Name from Editor and Goto Definition'. This function takes a string pointed by the caret, scans the Tag file and pushes ALL symbols having this name. No semantic information such as scopes or overloading resolution is taken into account. This is why this function is useful to find definition of a known symbol rather than to browse an existing code. Also this function does not permit browsing of local symbols, such as local variables, parameters and labels, as they are not recorded in global Tag file.

Browser Dialog

Browser dialog allows visualization of Xrefactory browser stack by displaying its top element. It contains two major information panes. Information displayed in information panes can be filtered by selecting filter from combo boxes placed above.

Toolbar

Browser toolbar contains four buttons putting new symbol(s) onto browser stack. Following four other functions are accessible from Toolbar:

Browse name

The browse name text field can be used to enter manually a name to be pushed onto the browser stack. This may be used when you wish to browse a symbol which you do not see in your source code. Otherwise, it is more natural to use either "Browse Name and Goto Definition" or "Browse Symbol and Goto Definition" funtion.

Symbol Pane

The symbol information pane contains symbol names, profile informations and classes where those symbols are defined. Window is organized as tree, where after each symbol follows inheritance subtree relevant for this symbol. Tree contains classes defining the symbol and (sub) classes where symbol is syntactically referred. After class name follows number of references.

Mouse key bindings:
<mouse-left-button>- select only one class references and inspect definition reference (or javadoc).
<mouse-right-button>- toggle select/unselect.
<SHIFT><mouse-left-button>- toggle select/unselect.
<CTRL><mouse-left-button>- inspect class (or its javadoc).

Available filters:
Equal name- all symbols of given name are displayed. Class tree is not restricted.
Equal profile- the browsed symbol is displayed. Class tree is not restricted.
Relevant- the browsed symbol is displayed. Class tree does not display classes not related to class of browsed symbol.

References Pane

The references pane contains list of references. Each reference is listed together with corresponding line of source code. The list is selectable and selected reference is automatically opened in editor.

Meaning of filters for classes:
Level 3: Only definitions and declarations are shown.
Level 2: as level 3 plus usages in the EXTENDS and IMPLEMENTS clauses
Level 1: as level 2 plus all usages in the top level scope (in global vars and method definitions). This can be used to see all the methods working with a particular type.
Level 0: all references are shown.

Meaning of filters for variables:
Level 3: only definition and declarations are shown.
Level 2: as level 3 plus l-value usages.
Level 1: (unused in Java language).
Level 0: all references.


Symbol retriever

Xrefactory symbol retriever serves for finding forgotten symbol names and for finding symbols from third parties libraries. You enter a string to search and Xrefactory scans Tags (optionally also jar archives from the claspath). All symbols matching entered string are reported.

Entered strings are interpreted as shell expressions and are composed from a sequence of characters possibly containing wild characters. Following wild characters can be used: * expands to any (possibly empty) string, ? expands to any single character and [...] pair expands to one of enclosed characters. Ranges of characters can be included between [ and ], so for example [a-zA-Z] matches any letter, [0-9] matches any digit, as it is usual in shell expressions. If the first character following the [ is a ^ then the sense of expansion is inversed, for example [^0-9] expands to any non-digit character. A symbol is reported only if it completely matches the searched string. Method profile is considered as part of the name of the method, for example, the expression *(*int*) will report all methods taking at least one parameter of type int. Letters are considered case unsensitive except letters enclosed between [ and ].

For example the expression *get* will report all symbols containing the string get, for example symbols getField and Target will match. Expression get* will report all symbols starting by the string 'get'. Expression [A-Z]* will report all symbols starting by an upper case letter. Expression get[abc0-2]* will report all symbols starting by the string 'get' followed by one of characters a,b,c,0,1,2 followed by any (possibly empty) string, so for example getact will match, but getAccount will not.

If you enter an expression which does not contain any of wild characters *, ? or [ then Xrefactory reports all symbols containing entered string. For example, entering get as the expression is equivalent to entering *get*.

Refactorer

Refactoring is a software development and maintenance process where the source code is changed in such a way that it does not alter the external behavior. Xrefactory offers automatic support for several general refactoring patterns available via refactorer function. Whenever it is possible it also checks that performed modifications do not change program behaviour. For example, in case of symbol renaming, Xrefactory checks whether renamed symbol does not clash with an existing one, etc.

Invocation of refactorer will display a pop up menu with refactorings available for symbol pointed by the caret. Selection of one of items will perform the refactoring.

Here follows the list of refactorings implemented by Xrefactory:



Feedback

 Any feedback as well as installation and usage support requests are welcomed at Xrefactory discussion forum.

License

 The plugin itself is released under GPL license. However, it requires Xrefactory installation (namely the 'xref' task) which is shareware. You are supposed to purchase valid license when using Xrefactory beyond the evaluation period. You can read the full license conditions and make your orders on the address: http://www.xref-tech.com/xrefactory/license.html.