org.eclipse.ltk.core.refactoring
Class RefactoringDescriptor

java.lang.Object
  org.eclipse.ltk.core.refactoring.RefactoringDescriptor

All Implemented Interfaces:

Comparable

public 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 are identified by their refactoring id getID() and their time stamps getTimeStamp().

Refactoring descriptors are potentially heavyweight objects which should not be held on to. Use refactoring descriptor handles RefactoringDescriptorProxy to store refactoring information.

Clients which create specific refactoring descriptors during change generation should choose an informative description of the particular refactoring instance and pass appropriate descriptor flags to the constructor. In particular, if a refactoring descriptor represents a refactoring which renames a project resource, the descriptor should have the flag PROJECT_CHANGE set and a valid argument NAME. The arguments INPUT or ELEMENT are reserved to specify the input arguments of a particular refactoring. The format of the values of these arguments is langugage-dependent, but should be standardized for a particular programming language. These arguments may be preprocessed by language-specific tools such as wizards to import refactoring information into the local workspace.

All time stamps are measured in UTC milliseconds from the epoch (see java.util#Calendar).

Note: this class is not indented to be subclassed outside the refactoring framework.

Note: This API is considered experimental and may change in the near future.

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	ELEMENT Predefined argument called element<Number>.
static String	INPUT Predefined argument called input.
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 String	NAME Predefined argument called name.
static int	NONE Constant describing the absence of any flags (value: 0)
static int	PROJECT_CHANGE Constant describing the project rename change flag (value: 8) Clients should set this flag to indicate that the represented refactoring renames a project resource in the workspace.
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

RefactoringDescriptor(String id, String project, String description, String comment, Map arguments, int flags)
Creates a new refactoring descriptor.

Method Summary

int	compareTo(Object object)
boolean	equals(Object object)
Map	getArguments() Returns the arguments describing the refactoring, in no particular order.
String	getComment() Returns the comment associated with this refactoring.
String	getDescription() Returns a human-readable description of this refactoring.
int	getFlags() Returns the flags of this refactoring.
String	getID() Returns the unique id of this refactoring.
String	getProject() Returns the name of the associated project.
long	getTimeStamp() Returns the time stamp of this refactoring.
int	hashCode()
boolean	isUnknown() Returns whether this descriptor describes an unknown refactoring.
void	setComment(String comment) Sets the comment 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

ELEMENT

public static final String ELEMENT

Predefined argument called element<Number>.

This argument should be used to describe the elements being refactored. The value of this argument does not necessarily have to uniquely identify the elements. However, it must be possible to uniquely identify the elements using the value of this argument in conjunction with the values of the other user-defined attributes.

The element arguments are simply distinguished by appending a number to the argument name, eg. element1. The indices of this argument are non zero-based.

See Also:

Constant Field Values

INPUT

public static final String INPUT

Predefined argument called input.

This argument should be used to describe the element being refactored. The value of this argument does not necessarily have to uniquely identify the input element. However, it must be possible to uniquely identify the input element using the value of this argument in conjunction with the values of the other user-defined attributes.

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

NAME

public static final String NAME

Predefined argument called name.

This argument should be used to describe the name of the element being refactored. The value of this argument may be displayed in the user interface.

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

PROJECT_CHANGE

public static final int PROJECT_CHANGE

Constant describing the project rename change flag (value: 8)

Clients should set this flag to indicate that the represented refactoring renames a project resource in the workspace. If this flag is set for a particular descriptor, the refactoring history service assumes that the argument NAME of the refactoring descriptor denotes the new name of the project being renamed.

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 values greater than this constant.

See Also:

Constant Field Values

Constructor Detail

RefactoringDescriptor

public RefactoringDescriptor(String id,
                             String project,
                             String description,
                             String comment,
                             Map arguments,
                             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

description - a non-empty human-readable description of the particular refactoring instance

comment - the comment associated with the refactoring, or null for no commment

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

Method Detail

compareTo

public final int compareTo(Object object)

Specified by:

compareTo in interface Comparable

equals

public final boolean equals(Object object)

getArguments

public final Map getArguments()

Returns the arguments describing the refactoring, in no particular order.

Returns:

the argument map (element type: <String, String>). The resulting map cannot be modified.

getComment

public final String getComment()

Returns the comment associated with this refactoring.

Returns:

the associated comment, or the empty string

getDescription

public final String getDescription()

Returns a human-readable description of this refactoring.

Returns:

a description of this refactoring

getFlags

public final int getFlags()

Returns the flags of this refactoring.

Returns:

the flags of this refactoring

getID

public final String getID()

Returns the unique id of this refactoring.

Returns:

the unique id

getProject

public final String getProject()

Returns the name of the associated project.

Returns:

the non-empty name of the project, or null

getTimeStamp

public final long getTimeStamp()

Returns the time stamp of this refactoring.

Returns:

the time stamp, or -1 if no time information is available

hashCode

public final int hashCode()

isUnknown

public boolean isUnknown()

Returns whether this descriptor describes an unknown refactoring.

The default implementation returns false.

Returns:

true if the descriptor describes an unknown refactoring, false otherwise

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

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 final String toString()