org.eclipse.ltk.core.refactoring
Class RefactoringDescriptor
java.lang.Object
org.eclipse.ltk.core.refactoring.RefactoringDescriptor
-
All Implemented Interfaces:
-
Comparable
-
Direct Known Subclasses:
-
DeleteResourcesDescriptor,
MoveResourcesDescriptor,
RenameResourceDescriptor
-
public abstract class RefactoringDescriptor
- extends
Object
- implements
Comparable
Descriptor object of a refactoring.
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:
- a short description string, which provides a human-readable text
designed to be displayed in the user interface to represent the refactoring
in trees and lists. Descriptions are automatically generated by refactorings.
- an optional comment string, which provides a full human-readable
description of the refactoring. Comments are automatically generated by
refactorings and provide more refactoring-specific information, such as which
elements have participated in the refactoring.
- refactoring descriptor flags, which tell the framework what capabilities
or properties a certain refactorings has when executed in a remote context.
- a timestamp, measured as the milliseconds since January 1, 1970,
00:00:00 GMT, which denotes the original execution time of the refactoring.
- a unique ID, which denotes a certain kind of refactoring (e.g. Rename
File). This ID is usually composed of the plugin identifier of the
contributing plugin and a plugin-wide unique identifier (e.g.
org.eclipse.ltk.core.refactoring.renameFile
).
- the optional name of the project this refactoring is associated with.
Note that the project name is not available if the refactoring cannot be
associated with a single project, or the refactoring descriptor has been read
from a file which cannot be associated with a project.
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.
-
Since:
- 3.2
-
See Also:
-
RefactoringDescriptorProxy
,
IRefactoringHistoryService
Field Summary
|
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 ). |
BREAKING_CHANGE
public static final int BREAKING_CHANGE
- Constant describing the API change flag (value:
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.
-
See Also:
-
Constant Field Values
ID_UNKNOWN
public static final
String ID_UNKNOWN
- The unknown refactoring id (value:
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.
-
See Also:
-
Constant Field Values
MULTI_CHANGE
public static final int MULTI_CHANGE
- Constant describing the multi change flag (value:
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.
-
See Also:
-
Constant Field Values
NONE
public static final int NONE
- Constant describing the absence of any flags (value:
0
).
-
See Also:
-
Constant Field Values
STRUCTURAL_CHANGE
public static final int STRUCTURAL_CHANGE
- Constant describing the structural change flag (value:
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.
-
See Also:
-
Constant Field Values
USER_CHANGE
public static final int USER_CHANGE
- Constant describing the user flag (value:
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.
-
See Also:
-
Constant Field Values
RefactoringDescriptor
protected RefactoringDescriptor(
String id,
String project,
String description,
String comment,
int flags)
- Creates a new refactoring descriptor.
-
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 human-readable comment of the particular refactoring
instance, or null
for no comment -
flags
- the flags of the refactoring descriptor
compareTo
public final int compareTo(
Object object)
-
-
-
Specified by:
-
compareTo
in interface
Comparable
-
createRefactoring
public abstract
Refactoring createRefactoring(
RefactoringStatus status)
throws
CoreException
- Creates the a new refactoring instance for this refactoring descriptor.
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 returned refactoring must be in an initialized state, i.e. ready to
be executed via
PerformRefactoringOperation
.
-
-
-
Parameters:
-
status
- a refactoring status used to describe the outcome of the
initialization
-
Returns:
- the refactoring, or
null
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
-
Throws:
-
CoreException
- if an error occurs while creating the refactoring instance
equals
public final boolean equals(
Object object)
-
-
-
Overrides:
-
equals
in class
Object
-
getComment
public final
String getComment()
- Returns the details comment.
This information is used in the user interface to show additional details
about the performed refactoring.
-
-
-
Returns:
- the details comment, or the empty string
getDescription
public final
String getDescription()
- Returns the description.
This information is used to label a refactoring in the user interface.
-
-
-
Returns:
- the description
getFlags
public final int getFlags()
- Returns the flags.
-
-
-
Returns:
- the flags
getID
public final
String getID()
- Returns the refactoring id.
-
-
-
Returns:
- the refactoring id.
getProject
public final
String getProject()
- Returns the project name.
-
-
-
Returns:
- the non-empty name of the project, or
null
getTimeStamp
public final long getTimeStamp()
- Returns the time stamp.
-
-
-
Returns:
- the time stamp, or
-1
if no time information is
available
hashCode
public final int hashCode()
-
-
-
Overrides:
-
hashCode
in class
Object
-
setComment
public void setComment(
String comment)
- Sets the details comment of this refactoring.
Note: This API must not be extended or reimplemented and should not be
called from outside the refactoring framework.
-
-
-
Parameters:
-
comment
- the comment to set, or null
for no comment
setDescription
public void setDescription(
String description)
- Sets the description of this refactoring.
Note: This API must not be extended or reimplemented and should not be
called from outside the refactoring framework.
-
-
-
Parameters:
-
description
- the non-empty description of the refactoring to set -
Since:
- 3.3
setFlags
public void setFlags(int flags)
- Sets the flags of this refactoring.
Note: This API must not be extended or reimplemented and should not be
called from outside the refactoring framework.
-
-
-
Parameters:
-
flags
- the flags to set, or NONE
to clear the flags -
Since:
- 3.3
setProject
public void setProject(
String project)
- Sets the project name of this refactoring.
Note: This API must not be extended or reimplemented and should not be
called from outside the refactoring framework.
-
-
-
Parameters:
-
project
- the non-empty project name to set, or null
for
the workspace
setTimeStamp
public void setTimeStamp(long stamp)
- Sets the time stamp of this refactoring. This method can be called only
once.
Note: This API must not be extended or reimplemented and should not be
called from outside the refactoring framework.
-
-
-
Parameters:
-
stamp
- the time stamp to set
toString
public
String toString()
-
-
-
Overrides:
-
toString
in class
Object
-
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.