public abstract class RefactoringContribution
Partial implementation of refactoring contribution objects which are capable
of creating refactoring descriptors or refactoring arguments.
Clients which would like to add refactoring history and refactoring scripting
support to a refactoring are required to register a subclass of
RefactoringContribution with the extension point
participate in the refactoring services. Refactoring contributions are
stateless objects. They are instantiated on demand by the refactoring
framework in the following cases:
- When a refactoring script is executed, the refactoring framework
retrieves a corresponding refactoring contribution for each refactoring
persisted in the script and calls
createDescriptor(String, String, String, String, Map, int) with the
appropriate arguments read from the refactoring script to obtain a
language-specific refactoring descriptor. This refactoring descriptor is then
used to dynamically construct the corresponding refactoring object and to
initialize the refactoring object afterwards. The returned refactoring object
is completely initialized and ready to be executed, ie. by
- After a refactoring has been executed, the refactoring framework stores
the returned refactoring descriptor into the global refactoring history.
During serialization of the descriptor, the refactoring framework calls
retrieveArgumentMap(RefactoringDescriptor) of the refactoring
contribution associated with the executed refactoring to obtain a neutral
key-value representation of the state of the language-specific refactoring
Refactorings for which a refactoring contribution has been registered should
also create a
during change generation. Their
return a change object whose
method returns a
that encapsulates the
Since 3.3, refactoring contributions may serve also as a uniform API to
expose language-specific refactorings. Clients wishing to provide
customizable refactoring descriptors may reimplement the method
Note: Clients which extend this class are required to reimplement the method
in subclasses to capture
the state of a language-specific refactoring descriptor in a neutral
key-value representation used by the refactoring framework. The default
implementation in this class only handles refactoring descriptors associated
with refactorings for which no corresponding refactoring contribution has
Methods inherited from class java.lang.
- Creates a new customizable refactoring descriptor initialized with its
This method may be reimplemented to return a language-specified
refactoring descriptor which can be initialized using language-specific
features. Refactoring tool providers may reimplement this method to
provide a uniform API to expose refactoring functionality in the form of
Callers of this method are supposed to cast the resulting refactoring
descriptor to the corresponding language-specific refactoring descriptor
provided by the API of the refactoring tooling provider.
Note: this method is supposed to be reimplemented by clients wishing to
provide customizable refactoring descriptors.
- the refactoring descriptor, or
null if the
refactoring represented by this contribution does not expose
customizable refactoring descriptors
createDescriptor(String, String, String, String, Map, int)
- Creates a new refactoring descriptor initialized with the values provided
by the arguments of this method.
This method is used by the refactoring framework to create a
language-specific refactoring descriptor representing the refactoring
instance corresponding to the specified arguments. Implementations of
this method must never return
null. The refactoring
framework guarantees that this method is only called with
values for which the refactoring contribution has been registered with
the extension point.
id - the unique id of the refactoring
project - the non-empty name of the project associated with this
null for a workspace
description - a non-empty human-readable description of the particular
comment - the comment associated with the refactoring, or
null for no comment
arguments - the argument map (element type: <String, String>). The
keys of the arguments are required to be non-empty strings
which must not contain spaces. The values must be non-empty
flags - the flags of the refactoring descriptor
- the refactoring descriptor
- if the argument map contains invalid keys/values
- Returns the refactoring id for which this refactoring contribution has
been registered with the extension point. Implementations of
createDescriptor() may use this method to initialize the
resulting refactoring descriptor with the id of this refactoring
Note: this method is not intended to be extended or reimplemented by
- the unique id of the refactoring
- This method is not intended to be re-implemented or extended by clients.
- Retrieves the argument map of the specified refactoring descriptor.
This method is used by the refactoring framework to obtain
refactoring-specific arguments provided by the refactoring descriptor.
These are the arguments which are specific to certain refactoring
instances, and correspond to the argument map which has been passed to
createDescriptor(String, String, String, String, Map, int) upon
creation of the refactoring descriptor.
The returned argument map (element type: <String, String>) must
satisfy the following conditions:
- The keys of the arguments are required to be non-empty strings which
must not contain spaces.
- The values must be non-empty
Note: Subclasses must extend this method to provide more specific
implementation in order to let the refactoring framework retrieve the
argument map from language-specific refactoring descriptors.
Implementations of this method must never return
The refactoring framework guarantees that this method is only called for
refactoring descriptors which have been obtained by a previous call to
createDescriptor(String, String, String, String, Map, int).
descriptor - the refactoring descriptor to retrieve its argument map
- the argument map of the specified refactoring descriptor
createDescriptor(String, String, String, String, Map, int)
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.