|
 |
|
| |
org.eclipse.ltk.core.refactoring
Class RefactoringContribution
java.lang.Object
org.eclipse.ltk.core.refactoring.RefactoringContribution
-
public abstract class RefactoringContribution
- extends
Object
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
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:
- 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
PerformRefactoringOperation.
- 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
descriptor.
Refactorings for which a refactoring contribution has been registered should
also create a
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().
Note: Clients which extend this class are required to reimplement the method
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.
-
Since:
- 3.2
|
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
RefactoringContribution
public RefactoringContribution()
createDescriptor
public
RefactoringDescriptor createDescriptor()
- Creates a new customizable refactoring descriptor initialized with its
default values.
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.
-
-
Returns:
- the refactoring descriptor, or
null if the
refactoring represented by this contribution does not expose
customizable refactoring descriptors -
Since:
- 3.3
-
See Also:
-
createDescriptor(String, String, String, String, Map, int)
createDescriptor
public abstract
RefactoringDescriptor createDescriptor(
String id,
String project,
String description,
String comment,
Map arguments,
int flags)
throws
IllegalArgumentException
- 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 id
values for which the refactoring contribution has been registered with
the extension point.
-
-
Parameters:
-
id - the unique id of the refactoring -
project - the non-empty name of the project associated with this
refactoring, or null for a workspace
refactoring -
description - a non-empty human-readable description of the particular
refactoring instance -
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
strings -
flags - the flags of the refactoring descriptor
-
Returns:
- the refactoring descriptor
-
Throws:
-
IllegalArgumentException
- if the argument map contains invalid keys/values -
See Also:
-
retrieveArgumentMap(RefactoringDescriptor)
getId
public
String getId()
- 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
contribution.
Note: this method is not intended to be extended or reimplemented by
clients.
-
-
Returns:
- the unique id of the refactoring
-
Since:
- 3.3
-
Restriction:
- This method is not intended to be re-implemented or extended by clients.
retrieveArgumentMap
public
Map retrieveArgumentMap(
RefactoringDescriptor descriptor)
- 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
strings
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).
-
-
Parameters:
-
descriptor - the refactoring descriptor to retrieve its argument map
-
Returns:
- the argument map of the specified refactoring descriptor
-
See Also:
-
createDescriptor(String, String, String, String, Map, int)
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
|
|
|
