public abstract class RefactoringContribution extends Object
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
org.eclipse.ltk.core.refactoring.refactoringContributions
to
participate in the refactoring services. Refactoring contributions are
stateless objects. They are instantiated on demand by the refactoring
framework in the following cases:
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
PerformRefactoringOperation
. 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
descriptor. RefactoringDescriptor
during change generation. Their
Refactoring.createChange(org.eclipse.core.runtime.IProgressMonitor)
should
return a change object whose Change.getDescriptor()
method returns a
RefactoringChangeDescriptor
that encapsulates the RefactoringDescriptor
.
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
createDescriptor()
.
retrieveArgumentMap(RefactoringDescriptor)
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
been registered.
Constructor and Description |
---|
RefactoringContribution() |
Modifier and Type | Method and Description |
---|---|
RefactoringDescriptor |
createDescriptor()
Creates a new customizable refactoring descriptor initialized with its
default values.
|
abstract RefactoringDescriptor |
createDescriptor(String id,
String project,
String description,
String comment,
Map arguments,
int flags)
Creates a new refactoring descriptor initialized with the values provided
by the arguments of this method.
|
String |
getId()
Returns the refactoring id for which this refactoring contribution has
been registered with the extension point.
|
Map |
retrieveArgumentMap(RefactoringDescriptor descriptor)
Retrieves the argument map of the specified refactoring descriptor.
|
public RefactoringDescriptor createDescriptor()
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 refactoring descriptors.
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.
null
if the
refactoring represented by this contribution does not expose
customizable refactoring descriptorscreateDescriptor(String, String, String, String, Map, int)
public abstract RefactoringDescriptor createDescriptor(String id, String project, String description, String comment, Map arguments, int flags) throws IllegalArgumentException
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 id
values for which the refactoring contribution has been registered with
the extension point.
id
- the unique id of the refactoringproject
- the non-empty name of the project associated with this
refactoring, or null
for a workspace
refactoringdescription
- a non-empty human-readable description of the particular
refactoring instancecomment
- the comment associated with the refactoring, or
null
for no commentarguments
- 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
stringsflags
- the flags of the refactoring descriptorIllegalArgumentException
- if the argument map contains invalid keys/valuesretrieveArgumentMap(RefactoringDescriptor)
public String getId()
createDescriptor()
may use this method to initialize the
resulting refactoring descriptor with the id of this refactoring
contribution.
Note: this method is not intended to be extended or reimplemented by clients.
public Map retrieveArgumentMap(RefactoringDescriptor 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:
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 null
.
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 mapcreateDescriptor(String, String, String, String, Map, int)
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.