Eclipse Platform
Release 3.2

org.eclipse.ltk.core.refactoring
Class RefactoringDescriptor

java.lang.Object
  extended byorg.eclipse.ltk.core.refactoring.RefactoringDescriptor
All Implemented Interfaces:
Comparable

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:

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) Clients should set this flag to indicate that the represented refactoring may cause breaking API changes.
static 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.
static 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.
static int NONE
          Constant describing the absence of any flags (value: 0)
static 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.
static int USER_CHANGE
          Constant describing the user flag (value: 256) This constant is not intended to be used in refactoring descriptors.
 
Constructor Summary
protected RefactoringDescriptor(String id, String project, String description, String comment, int flags)
          Creates a new refactoring descriptor.
 
Method Summary
 int compareTo(Object object)
          
abstract  Refactoring createRefactoring(RefactoringStatus status)
          Creates the a new refactoring instance for this refactoring descriptor.
 boolean equals(Object object)
          
 String getComment()
          Returns the 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 comment 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()
          
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

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_CHANGE flag, they should set STRUCTURAL_CHANGE as well.

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.

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.

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 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
Method Detail

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)


getComment

public final String getComment()
Returns the comment.

Returns:
the comment, or the empty string

getDescription

public final String getDescription()
Returns the description.

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()


setComment

public final void setComment(String comment)
Sets the comment of this refactoring.

Note: This API must not be called from outside the refactoring framework.

Parameters:
comment - the non-empty comment to set, or null

setProject

public final void setProject(String project)
Sets the project name of this refactoring.

Note: This API must not be called from outside the refactoring framework.

Parameters:
project - the non-empty project name to set, or null for the workspace

setTimeStamp

public final void setTimeStamp(long stamp)
Sets the time stamp of this refactoring. This method can be called only once.

Note: This API must not be called from outside the refactoring framework.

Parameters:
stamp - the time stamp to set

toString

public String toString()


Eclipse Platform
Release 3.2

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2006. All rights reserved.