Class RefactoringDescriptor
- java.lang.Object
-
- org.eclipse.ltk.core.refactoring.RefactoringDescriptor
-
- All Implemented Interfaces:
Comparable<RefactoringDescriptor>
- Direct Known Subclasses:
DeleteResourcesDescriptor,MoveRenameResourceDescriptor,MoveResourcesDescriptor,RenameResourceDescriptor
public abstract class RefactoringDescriptor extends Object implements Comparable<RefactoringDescriptor>
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 stampsgetTimeStamp()and are potentially heavy weight objects which should not be held on to. Use refactoring descriptor proxiesRefactoringDescriptorProxyto 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
Fields Modifier and Type Field Description static intBREAKING_CHANGEConstant describing the API change flag (value:1).static StringID_UNKNOWNThe unknown refactoring id (value:org.eclipse.ltk.core.refactoring.unknown).static intMULTI_CHANGEConstant describing the multi change flag (value:4).static intNONEConstant describing the absence of any flags (value:0).static intSTRUCTURAL_CHANGEConstant describing the structural change flag (value:2).static intUSER_CHANGEConstant describing the user flag (value:256).
-
Constructor Summary
Constructors Modifier Constructor Description protectedRefactoringDescriptor(String id, String project, String description, String comment, int flags)Creates a new refactoring descriptor.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description intcompareTo(RefactoringDescriptor descriptor)abstract RefactoringcreateRefactoring(RefactoringStatus status)Creates the a new refactoring instance for this refactoring descriptor.RefactoringContextcreateRefactoringContext(RefactoringStatus status)Creates the a new refactoring context and the associated refactoring instance for this refactoring descriptor.booleanequals(Object object)StringgetComment()Returns the details comment.StringgetDescription()Returns the description.intgetFlags()Returns the flags.StringgetID()Returns the refactoring id.StringgetProject()Returns the project name.longgetTimeStamp()Returns the time stamp.inthashCode()voidsetComment(String comment)Sets the details comment of this refactoring.voidsetDescription(String description)Sets the description of this refactoring.voidsetFlags(int flags)Sets the flags of this refactoring.voidsetProject(String project)Sets the project name of this refactoring.voidsetTimeStamp(long stamp)Sets the time stamp of this refactoring.StringtoString()
-
-
-
Field Detail
-
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_CHANGEflag, they should setSTRUCTURAL_CHANGEas 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 forIRefactoringExecutionListenerorIRefactoringHistoryListenerin 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
-
-
Constructor Detail
-
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 refactoringproject- the non-empty name of the project associated with this refactoring, ornullfor a workspace refactoringdescription- a non-empty human-readable description of the particular refactoring instancecomment- the human-readable comment of the particular refactoring instance, ornullfor no commentflags- the flags of the refactoring descriptor
-
-
Method Detail
-
compareTo
public final int compareTo(RefactoringDescriptor descriptor)
- Specified by:
compareToin interfaceComparable<RefactoringDescriptor>- Since:
- 3.7
-
createRefactoring
public abstract Refactoring createRefactoring(RefactoringStatus status) throws CoreException
Creates the a new refactoring instance for this refactoring descriptor.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.- Parameters:
status- a refactoring status used to describe the outcome of the initialization- Returns:
- the refactoring, or
nullif 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
-
createRefactoringContext
public RefactoringContext createRefactoringContext(RefactoringStatus status) throws CoreException
Creates the a new refactoring context and the associated 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 default implementation of this method wraps the refactoring in a trivial refactoring context. Subclasses may override this method to create a custom refactoring context.
- Parameters:
status- a refactoring status used to describe the outcome of the initialization- Returns:
- the refactoring context, or
nullif 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 context- Since:
- 3.6
-
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
-1if no time information is available
-
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, ornullfor 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, orNONEto 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, ornullfor 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
-
-