Participating in Refactorings

Support Java references outside Java code. References to Java elements in particular classes can show up in specific kinds of non-Java source files, such as plug-in manifest files (plugin.xml), extension point schema files, and Java launch configurations in the workspace. These references should also participate in Java operations like search, move, rename, and other refactoring operations. JDT will surface APIs that enable other plug-ins to contribute to and participate in these operations. [JDT Core, JDT UI, JDT Debug, PDE] [Theme: Extended Java family]

This document doesn't cover search or other functions also mentioned in the above plan item.

Last modified: July 28, 2003

Motivation

The current refactoring implementation has the following three shortcomings:

1. refactoring support is limited to Java resources. As a result all current refactorings don't update references to Java elements contained in non-Java files. It is desirable for example that renaming a class also updates launch configurations and plugin.xml files. Or that renaming a method updates references in JSP files. Additionally tools that deal with logical resources (resources consisting of a couple of physical resources) want to keep the logical resource consistent if a physical resource gets changed. For example a EJB maps to three different Java files: bean.java, beanr.java, beanlocal.java. Changing the name of bean.java should update beanr.java and beanlocal.java as well.
2. the implementation is internal to JDT/UI packages and not exposed as API. Other plug-ins can neither add new Java refactorings nor can they reuse the refactoring infrastructure to code refactorings for other programming languages.
3. Refactoring based actions are only available in JDT/UI views and editors. For example, triggering a rename on a *.java file which is on the build path of a Java project doesn't activate a rename compilation unit refactoring in the resource navigator. Instead the user gets a normal resource rename dialog.

This document focusses on items 1 and 3.

The Current Implementation

Although refactoring is located in the JDT/UI plug-in it is already separated into a UI and a core layer:

• Core: the main core abstractions are Refactoring and IChange. A concrete refactoring (e.g a subclass of class Refactoring) is responsible for precondition checking and change creation (e.g returning an instance of class IChange). The precondition checking is split into two phases:
1. activation checking: this is a "fast" check (no progress reporting) used to find out if the refactoring can be executed in general. It is called when a refactoring action is triggered, but before the refactoring UI is presented. If it returns a fatal error then the refactoring UI isn't presented at all.
2. user input checking: this is an exhaustive check (with progress reporting) based on the refactoring itself and the user input. It is performed when the user presses the OK or Preview button on the refactoring UI.
When executing a refactoring head-less both checks are combined into one single precondition checking method. An IChange object is responsible for performing the actual source manipulations. It is also responsible to produce an undo object.
• UI: the refactoring UI is wizard based and consists of 1 .. n input pages, a page presenting errors resulting from precondition checking and a page that shows a preview of the refactoring changes.

The Proposal

To enable other plug-ins to participate in certain refactorings their implementations are split into a processor/participant architecture. An extensible refactoring has one processor and 0 .. n participants. The major characteristics of processors and participants are:

• Processor: the main actor of a refactoring. It can exist without any participants. A processor is almost identical to a current refactoring and is determined based on the element to be refactored.
• Participant: participates in a refactoring. A participant can't exist without a processor and is determined based on the element to be refactored. A participant can participate in precondition checking and change creation. There is no support for participants to provide additional UI. A typical participant, provided by a JSP/Web plug-in, is a rename method participant. The participant updates references to the method to be renamed in JSP files. This includes both updating references in embedded Java code as well as updating references in tags (e.g. usebean tag, etc.).

  Participants can only participate in changes triggered by a processor. There is no support to participate in changes caused by another participant. The processor/participant architecture will not support arbitrary refactoring composition. Refactoring composition requires that a precondition check describes its result in some kind of postcondition which is then used as input for precondition checking of the next sibling refactoring in the composite. Consider the following example: a composite refactoring consists of the two refactorings (a) create class A.java and (b) add a method to A.java. One precondition check of refactoring (b) is: does A.java exist? Therefore evaluating the preconditions of both refactorings in isolation will fail. In contrast precondition checking in the processor/participant architecture assumes that the changes performed by the processor and the participants are "unrelated" to each other and therefore the preconditions can be checked in isolation.

Both processors and participants are contributed via extension points. XML expressions (comparable to those used for contributing to a pop-up menu) are used to describe their availability.

For each refactoring that is split into a processor/participant there is a "generic" action. This action creates a generic refactoring responsible to find the right processor and participants depending on the element(s) selected. Having such a generic action ensures that the same refactoring is triggered independent from where the refactoring is activated. The UI for the refactoring is determined by the processor chosen to process the element. Since processors and participants create errors and change objects typically not known by the refactoring framework the error and preview page must be extensible as well. The concrete status error viewer is picked depending on the type of status returned from precondition checking. The type of the change objects determines the concrete preview viewer. Additionally special content providers are needed for different change types to ensure proper rendering the of tree presenting all changes.

The picture below presents an overview of the new processor/participant split. Classes labeled as "generic" are provided by the refactoring framework. Classes labeled as "concrete" are concrete implementations provided by clients. A dashed line expresses a references between classes configurable via extension points. Solid lines indicate a fixed reference not configurable by client plug-ins.

The details of the processor/participant architecture are illustrated by examples. Please note that JDT/UI is the home of the current implementation. Hence all extension points are prefixed with org.eclipse.jdt.ui. This will change when the code is moved into a separate plug-in.

Renaming a Java method

Renaming method A#foo() into A#bar() takes place according to the following steps:

1. The generic rename refactoring searches in Eclipse's registry for a processor that is able to "rename" a Java method. An example of a processor capable to rename a Java method is:

   <renameProcessor
       id="org.eclipse.jdt.renameProcessor.Method"
       class="org.eclipse.jdt.internal.corext.refactoring.rename.RenameMethodProcessor">
       <objectState>
   	<property name="instanceof" value="org.eclipse.jdt.core.IMethod"/>
       </objectState>
   </renameProcessor>

   Due to its extensibility the new generic rename refactoring can only assume that it is renaming an element of type object. Hence a Java method rename processor must constrain its availability to IMethods. The <objectState> element can be used to describe a processor's availability depending on the state of the element to be renamed. Section Property Evaluation in Plugin.xml Files provides an overview of the property evaluation mechanism used by the refactoring plug-in.

   The rename action is disabled if no processor can be found.

2. Find all interested participants of a Java method rename. A typical rename Java method participant looks as follows:

   <renameParticipant
       class="org.example.jsp.refactoring.RenameMethodParticipant"
       id="org.example.jsp.refactoring.renameMethodParticipant">
       <projectScope>
           <property name="nature" value="org.example.jsp.core.jspnature"/>
       </projectScope>
       <objectState>
           <property name="instanceof" value="org.eclipse.jdt.core.IMethod"/>
   	<property name="isPrivate" value="false"/>
       </objectState>
   </renameParticipant>	

   Since participants are typically defined in higher level pug-ins care must be taken to avoid unnecessary plug-in loading. This is achieved by a two step approach:

   1. the refactoring processor is responsible to compute a set of affected projects, called the project scope of the refactoring. E.g. when renaming a Java method these are all projects which directly or indirectly reference the project in which the method to be renamed is declared. Refactoring processors for other languages might use a different algorithm to compute the set of affected projects. A refactoring participant must provide a <projectScope> element. The participant gets only loaded, if at least one project of the project scope set matches the expression in the <projectScope> element. In the example above this means the JSP rename method participant gets only loaded iff one of the affected projects has a JSP nature. This ensures that the JSP participant gets only loaded if the user does JSP development.
   2. Besides the project scope a refactoring participant has to provide an <objectState> element to express for which objects it is applicable. In the example above the rename method participant in the JSP world is applicable to IMethods. Furthermore it requires that the method isn't private (since private methods can't be referenced outside its declaring type renaming them can't affect any JSP files).

   Both projectScope and objectState are mandatory.

3. Compute the activation status of the rename refactoring by considering activation status of the processor and all participants. If the returned status doesn't contain any fatal error, determine the UI depending on the state of the processor. Processors are UI independent hence they can't have any references to the UI. So the processor UI relationship must be defined somewhere else. This is done by describing the relationship in XML as well.

   <refactoringWizard
       id="org.eclipse.jdt.renameProcessor.ui.IMethod"
       class="org.eclipse.jdt.internal.ui.refactoring.reorg.RenameMethodWizard">
       <objectState>
           <property name="instanceof" value="org.eclipse.jdt.internal.corext.refactoring.rename.RenameMethodProcessor"/>
       </objectState>
   </refactoringWizard>

4. When the user presses the OK or Preview button the processor forwards the collected input (e.g new name, etc.) to all participants. Next user input checking is performed considering the rename processor and all loaded participants. Depending on the outcome of this check, the refactoring is executed by computing a composite change containing the changes from the processor and the participants.
5. Picking the right error and preview viewer happens analogous to other viewer selection in Eclipse.

Derived Elements

The concept of derived elements is discussed using the rename Java field refactoring. Fields are commonly used as properties with corresponding setter and getter methods. A special rename field refactoring is aware of this relationship and renames the setter and getter method when the field gets renamed. Participants are contributed based on the element to be changed. Since the main element is a field no rename method participants are loaded. Therefore a processor can provide a set of additional elements that it manipulates. These elements are called derived elements. In contrast to participants that work on the main element (in our example the Java field), derived participants may depend on user input. E.g. in JDT renaming the corresponding setter and getter of a field can be controlled by the user. So derived participants can only be loaded after the user has pressed the finish or preview button. Since they missed the check activation phase of the precondition checking the result of the activation check of derived participants is merged into the result of the processor's input checking.

Resource Modifications

The concept of resource modifications is discussed using the rename Java package refactoring. Although packages are mapped to folders on the file system, renaming a package is a different operation than renaming its underlying folder. Renaming a package maps to the following resource operations:

1. create a folder with the new name, if such a folder doesn't exist yet.
2. move all files from the underlying folder to the new folder created in step 1.
3. delete the underlying folder if it is empty.

Now consider the following example: package p1 contains Java and HTML files. Additionally, there is a HTML plug-in that wants to participate in moving HTML files to update href elements in other HTML files. Since a HTML plug-in doesn't know anything about Java it can't participate in renaming a package. Even if it had a reference to the Java plug-in, participating in a package rename to determine this situation would require that the HTML plug-in doubles the logic for mapping a package rename to the underlying file system. To solve this problem a refactoring processor must express higher level operations in terms of resource modifications when possible. These resource modifications are then taken to determine the appropriate set of participants. This means for the HTML plug-in that it is enough to register a file move participant. Like participants for derived elements participants for resource modifications are computed after user input. Hence their activation checking is merged into the processors input checking as well.

Specializing Processors

Source folders (package fragment roots) are a special kind of folders. Besides their underlying folder on disk additional information about the build path and the output folder is associated with a source folder. Will there be a special rename source folder processor or a folder rename participant? The Java model offers a method to rename a source folder which updates the necessary build path information. Therefore implementing s source folder rename with a participant duplicates that code in a participant. Furthermore the provided delta looks different. A participant implementation triggers the following deltas:

• a resource delta notifying about the folder rename.
• a Java model delta notifying about the build path changes.
• a Java model delta notifying about the source folder rename without build path updates. This delta occurs since the Java model listens to resource deltas and tries to map them back to Java model deltas.

A special source folder processor triggers the following deltas:

• a Java model delta notifying about the source folder rename and the build path update.
• a resource delete notifying the folder rename.

Clearly the second delta is more appropriate. It is exactly what clients listening to deltas expect. Therefore the source folder rename is implemented using a special processor. For the given example the two processors are defined as follows:

#### The processor to rename resource (files, folders, projects, ....)
<renameProcessor
    id="org.eclipse.jdt.renameProcessor.IResource"
    class="org.eclipse.jdt.internal.corext.refactoring.rename.RenameResourceProcessor">
    <objectState>
        <property name="instanceof" value="org.eclipse.core.resources.IResource"/>
    </objectState>
</renameProcessor>

#### The processor to rename source folders
<renameProcessor
    id="org.eclipse.jdt.renameProcessor.IPackageFragmentRoot"
>>  override="org.eclipse.jdt.renameProcessor.IResource"
    class="org.eclipse.jdt.internal.corext.refactoring.rename.RenameSourceFolderProcessor">
    <objectState>
      <or>
        <property name="instanceof" value="org.eclipse.jdt.core.IPackageFragmentRoot"/>
        <and>
            <property name="instanceof" value="org.eclipse.core.resources.IFolder"/>
            <property name="isSourceFolder" value="true"/>
        </and>
      </or>
    </objectState>     
</renameProcessor>

With the override attribute (marked with ">>"" in the above example) the rename package fragment root processor specifies that it replaces the rename resource processor if its object state matches. This is the case if the element to be renamed is of instance IPackageFragmenRoot (which is the case if a source folder is selected in the package explorer) or if the element is of instance IFolder and it can be converted into a source folder (which is the case if a source folder is selected in the resource navigator).

What happens if the processor isn't unique for an element? In this case the user has to decide which processor he wants to use to perform the refactoring. Analogous to the Open With menu item the user is able to define a preferred processor to avoid unnecessary user arbitration.

Property Evaluation in Plugin.xml Files

To avoid unnecessary plug-in activation processor and participant contributions need means to describe there availability. The current implementation uses an extensible property evaluation mechanism to do so. I implemented a new mechanism instead of using the existing IActionFilter mechanism due to the following reasons:

• IActionFilter is part of Platform/UI, but processors and participants are UI independent functionality.
• IActionFilters are registered with the adaptable mechanism. Hence there can only be one action filter per type. E.g. there can't be two property testers for ICompilationUnit contributed by different plug-ins.
• IActionFilter interprets the case that a property can't be evaluated because the plug-in providing the tester isn't loaded yet as true. This can result in unneeded plug-in activation. The new implementation uses the three values: FALSE, TRUE, NOT_LOADED. Testing for an unknown property results in a core exception since it is a programming error.
• Action enablement in the UI supports the notion of "adaptable". If requested, the workbench adapts the element to be checked to IContributorResourceAdapter. In an open refactoring architecture the class to which the element is to be adapted must be configurable. The new property implementation supports such a mechanism in the form of <objectState adaptable="classname">. The key passed to IAdaptable.getAdapter must be an object of type Class, not a string. Therefore the class name must be converted into a Class object, which can lead to plug-in class loading. The class loader of the plug-in containing the <objecState adaptable="..."> element is used to convert the class name into a Class. Therefore only required plug-ins might be loaded by this mechanism (no upcalls). Additionally, availability checks take place on user actions, hence no unnecessary plug-in loading takes place on start-up.

Defining a new property tester is done in XML in the following way:

<extension point="org.eclipse.jdt.ui.propertyTesters">
    <propertyTester
        id="IResourcePropertyTester
        type="org.eclipse.core.resources.IResource"
        properties="name, projectNature"
        class="org.eclipse.jdt.internal.corext.refactoring.participants.xml.ResourcePropertyTester"/>
</extension>

The attributes do have the following meaning:

• id: a unique id
• type: the type the property tester is working on
• properties: the properties the tester can handle. Enumerating the properties in XML ensure that a property tester only gets loaded iff it can handle the property.
• class: the class implementing the property tester.

To ensure optimal performance for instance of checks (they are the most used property tests), the "instanceof" property is pre-defined and not contributed.

Implementation

A first implementation of the proposed processor/participant architecture exists in the JDT/UI plugin. The relevant packages are:

• org.eclipse.jdt.internal.corext.refactoring.participants: defines the protocol processor and participants must conform to. The most relevant interfaces are: IRefactoringProcessor and IRefactoringParticipant. The package also contains processor and participant definitions for rename, move, delete, etc.
• org.eclipse.jdt.internal.corext.refactoring.participants.xml: contains the extensible property tester mechanism.
• org.eclipse.jdt.internal.corext.refactoring.rename: contains concrete rename processors for Java elements.
• org.eclipse.jdt.internal.ui.refactoring: contains the refactoring UI with support for pluggable status and preview viewers.

The plugin org.eclipse.jdt.ui.examples.javafamily contains a rename type participant to update type references in JSPs.

As always you understand ideas better after you have written them down. Therefore the proposal contains some concepts not yet implemented or implemented in a different way.

Open Issues

The refactoring undo implementation has several shortcomings. The shortcomings mainly originate from the fact that refactoring was written for Java files only. The undo manager makes the following assumptions:

• before a refactoring is executed all dirty files (opened in an editor) are saved. This is necessary to have a "sync" point between the editor's local undo stack and the refactoring undo stack. Before a refactoring is undone the manager checks if there are dirty files affected by the undo operation. If this is the case then undo can't be performed.
• the undo manager flushes the undo stack as soon as a Java resource gets modified (it listens to Java model deltas). In an open refactoring architecture this can't be sustained. Arbitrary resources can be modified. We have evaluated two approaches to solve this problem locally in the refactoring framework. But as outlined both approaches have been dismissed:
  • the refactoring change objects register themselves as change listeners with their corresponding delta provider. For example resource change objects register themselves as resource change listeners, Java change objects register themselves as Java change listeners, etc. Depending on the delta they enable or disable themselves. Before an undo operation is performed the manager checks if all undo objects are still enabled. Since this solution leads to a high number of change listeners (there can be hundreds of change objects) we dismissed it when implementing the current refactoring infrastructure. It noticably slows down change notification.
  • before a refactoring is undone the manager asked all change objects if they are still valid. We dismissed this solution as well since an undo change object can depend on the result of a previous undo object. Consider the following case with two change objects: change one modifies file A.java, change two deletes it. Asking the corresponding undo changes in isolation if they can be undone answers no since file A.java doesn't exist anymore. Undo change one relies on the fact that undo change two restores file A.java.

The platform is working on a new context concept to limit the number of available actions. We should check if the <projectState> element for participants can leverage the new context concept.

Summary

• There is one generic action for refactorings like rename, move, delete, etc.
• Extensible refactorings are implemented using a processor/participant architecture. Both processors and participants are contributed via XML.
• There are three types of participants:
  1. participants that operate on the original element to be modified.
  2. participants that operate on elements derived from the original element.
  3. participants that operate on the corresponding resource modifications.
• Participants can't contribute to the UI, although this would be possible for participants of category (1) if required.
• There is no support to participate in changes done by a participant. Participants can only participate in processor operations.
• No support will be provided for composite refactorings.
• Processors can override each other to provide a more specific processor for more specific elements.
• The new refactoring UI is wizard/dialog based as the current Java refactoring UI. The relationship between UI and processors is described in XML. Furthermore special error and preview viewers can be contributed.
• To support undo in an open refactoring architecture some enhanced undo support from platform is needed.