public abstract class RefactoringDescriptor extends Object implements Comparable
A refactoring descriptor contains refactoring-specific data which allows the framework to completely reconstruct a particular refactoring instance and execute it on an arbitrary workspace.
Refactoring descriptors contain the following information:
org.eclipse.ltk.core.refactoring.renameFile
).
Refactoring descriptors are identified by their refactoring id
getID()
and their time stamps getTimeStamp()
and are
potentially heavy weight objects which should not be held on to. Use
refactoring descriptor proxies RefactoringDescriptorProxy
to present
refactoring descriptors in the user interface or otherwise manipulate
refactoring histories.
Clients which create specific refactoring descriptors during change generation should choose a short, informative and human-readable description of the particular refactoring instance and pass appropriate descriptor flags to the constructor. More details about a particular refactoring can be revealed in the comment, which contains more text with refactoring-specific information.
Refactoring descriptors do not provide version information. It is the responsibility of the client to enhance subclasses with refactoring version information in order to provide a means of schema evolution.
All time stamps are measured as the milliseconds since January 1, 1970, 00:00:00 GMT.
Note: this class is indented to be subclassed by clients to provide specialized refactoring descriptors for particular refactorings.
RefactoringDescriptorProxy
,
IRefactoringHistoryService
Modifier and Type | Field and Description |
---|---|
static int |
BREAKING_CHANGE
Constant describing the API change flag (value:
1 ). |
static String |
ID_UNKNOWN
The unknown refactoring id (value:
org.eclipse.ltk.core.refactoring.unknown ). |
static int |
MULTI_CHANGE
Constant describing the multi change flag (value:
4 ). |
static int |
NONE
Constant describing the absence of any flags (value:
0 ). |
static int |
STRUCTURAL_CHANGE
Constant describing the structural change flag (value:
2 ). |
static int |
USER_CHANGE
Constant describing the user flag (value:
256 ). |
Modifier | Constructor and Description |
---|---|
protected |
RefactoringDescriptor(String id,
String project,
String description,
String comment,
int flags)
Creates a new refactoring descriptor.
|
Modifier and Type | Method and Description |
---|---|
int |
compareTo(Object object) |
abstract Refactoring |
createRefactoring(RefactoringStatus status)
Creates the a new refactoring instance for this refactoring descriptor.
|
RefactoringContext |
createRefactoringContext(RefactoringStatus status)
Creates the a new refactoring context and the associated refactoring instance for this
refactoring descriptor.
|
boolean |
equals(Object object) |
String |
getComment()
Returns the details comment.
|
String |
getDescription()
Returns the description.
|
int |
getFlags()
Returns the flags.
|
String |
getID()
Returns the refactoring id.
|
String |
getProject()
Returns the project name.
|
long |
getTimeStamp()
Returns the time stamp.
|
int |
hashCode() |
void |
setComment(String comment)
Sets the details comment of this refactoring.
|
void |
setDescription(String description)
Sets the description of this refactoring.
|
void |
setFlags(int flags)
Sets the flags of this refactoring.
|
void |
setProject(String project)
Sets the project name of this refactoring.
|
void |
setTimeStamp(long stamp)
Sets the time stamp of this refactoring.
|
String |
toString() |
public static final int BREAKING_CHANGE
1
).
Clients should set this flag to indicate that the represented refactoring
may cause breaking API changes. If clients set the
BREAKING_CHANGE
flag, they should set STRUCTURAL_CHANGE
as well. Typically, refactorings which change elements that are marked as
API according to the semantics of the associated programming language
should set this flag. This flag is used by the refactoring framework to
determine whether a refactoring may break existing API when replayed by
clients.
public static final String ID_UNKNOWN
org.eclipse.ltk.core.refactoring.unknown
).
This id is reserved by the refactoring framework to signal that a
refactoring has been performed which did not deliver a refactoring
descriptor via its Change.getDescriptor()
method. The refactoring
history service never returns unknown refactorings. For consistency
reasons, they are reported for IRefactoringExecutionListener
or
IRefactoringHistoryListener
in order to keep clients of these
listeners synchronized with the workbench's operation history.
public static final int MULTI_CHANGE
4
).
Clients should set this flag to indicate that the change created by the represented refactoring might causes changes in other files than the files of the input elements according to the semantics of the associated programming language. Typically, refactorings which update references to the refactored element should set this flag. This flag is used during team synchronize operations to optimize the processing of refactorings.
public static final int NONE
0
).public static final int STRUCTURAL_CHANGE
2
).
Clients should set this flag to indicate that the change created by the represented refactoring might be a structural change according to the semantics of the associated programming language. Typically, refactorings which cause changes in elements other than the element which declares the refactored element should set this flag. This flag is used by language-specific tools to determine whether the refactoring may impact client code.
public static final int USER_CHANGE
256
).
This constant is not intended to be used in refactoring descriptors. Clients should use the value of this constant to define user-defined flags with integer values greater than this constant. Clients must not use this constant directly.
protected RefactoringDescriptor(String id, String project, String description, String comment, int flags)
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 human-readable comment of the particular refactoring
instance, or null
for no commentflags
- the flags of the refactoring descriptorpublic final int compareTo(Object object)
compareTo
in interface Comparable
public abstract Refactoring createRefactoring(RefactoringStatus status) throws CoreException
The returned refactoring must be in an initialized state, i.e. ready to
be executed via PerformRefactoringOperation
.
This method is not intended to be called directly from code that does not belong to this
class and its subclasses. External code should call
createRefactoringContext(RefactoringStatus)
and obtain the refactoring object from
the refactoring context.
status
- a refactoring status used to describe the outcome of the initializationnull
if this refactoring
descriptor represents the unknown refactoring, or if no
refactoring contribution is available for this refactoring
descriptor which is capable to create a refactoringCoreException
- if an error occurs while creating the refactoring instancepublic RefactoringContext createRefactoringContext(RefactoringStatus status) throws CoreException
This method is used by the refactoring framework to instantiate a refactoring from a refactoring descriptor, in order to apply it later on a local or remote workspace.
The default implementation of this method wraps the refactoring in a trivial refactoring context. Subclasses may override this method to create a custom refactoring context.
status
- a refactoring status used to describe the outcome of the initializationnull
if this refactoring
descriptor represents the unknown refactoring, or if no
refactoring contribution is available for this refactoring
descriptor which is capable to create a refactoring.CoreException
- if an error occurs while creating the refactoring contextpublic final String getComment()
This information is used in the user interface to show additional details about the performed refactoring.
public final String getDescription()
This information is used to label a refactoring in the user interface.
public final int getFlags()
public final String getID()
public final String getProject()
null
public final long getTimeStamp()
-1
if no time information is
availablepublic void setComment(String comment)
Note: This API must not be extended or reimplemented and should not be called from outside the refactoring framework.
comment
- the comment to set, or null
for no commentpublic void setDescription(String description)
Note: This API must not be extended or reimplemented and should not be called from outside the refactoring framework.
description
- the non-empty description of the refactoring to setpublic void setFlags(int flags)
Note: This API must not be extended or reimplemented and should not be called from outside the refactoring framework.
flags
- the flags to set, or NONE
to clear the flagspublic void setProject(String project)
Note: This API must not be extended or reimplemented and should not be called from outside the refactoring framework.
project
- the non-empty project name to set, or null
for
the workspacepublic void setTimeStamp(long stamp)
Note: This API must not be extended or reimplemented and should not be called from outside the refactoring framework.
stamp
- the time stamp to set
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.