org.eclipse.jdt.core.refactoring.descriptors

## Class JavaRefactoringDescriptor

- java.lang.Object
- - org.eclipse.ltk.core.refactoring.RefactoringDescriptor
  - - org.eclipse.jdt.core.refactoring.descriptors.JavaRefactoringDescriptor

All Implemented Interfaces:
  Comparable<RefactoringDescriptor>

Direct Known Subclasses:
  ChangeMethodSignatureDescriptor, ConvertAnonymousDescriptor, ConvertLocalVariableDescriptor, ConvertMemberTypeDescriptor, CopyDescriptor, DeleteDescriptor, EncapsulateFieldDescriptor, ExtractClassDescriptor, ExtractConstantDescriptor, ExtractInterfaceDescriptor, ExtractLocalDescriptor, ExtractMethodDescriptor, ExtractSuperclassDescriptor, GeneralizeTypeDescriptor, InferTypeArgumentsDescriptor, InlineConstantDescriptor, InlineLocalVariableDescriptor, InlineMethodDescriptor, IntroduceFactoryDescriptor, IntroduceIndirectionDescriptor, IntroduceParameterDescriptor, IntroduceParameterObjectDescriptor, MoveDescriptor, MoveMethodDescriptor, MoveStaticMembersDescriptor, PullUpDescriptor, PushDownDescriptor, RenameJavaElementDescriptor, RenameLocalVariableDescriptor, RenameResourceDescriptor, UseSupertypeDescriptor

    public abstract class JavaRefactoringDescriptor
    extends RefactoringDescriptor

Partial implementation of a java refactoring descriptor.

This class provides features common to all Java refactorings.

Note: this class is not intended to be extended outside the refactoring framework.

Since:
  1.1
Restriction:
  This class is not intended to be subclassed by clients outside JDT.

### Field Summary

Fields
`protected static String` `ATTRIBUTE_ELEMENT` Predefined argument called `element<Number>`.
`protected static String` `ATTRIBUTE_INPUT` Predefined argument called `input`.
`protected static String` `ATTRIBUTE_NAME` Predefined argument called `name`.
`protected static String` `ATTRIBUTE_REFERENCES` Predefined argument called `references`.
`protected static String` `ATTRIBUTE_SELECTION` Predefined argument called `selection`.
`protected static String` `ATTRIBUTE_VERSION` The version attribute
`protected Map<String,String>` `fArguments` The argument map (key type: `String`, value type: `String`).
`static int` `JAR_MIGRATION` Constant describing the jar migration flag (value: `65536`).
`static int` `JAR_REFACTORING` Constant describing the jar refactoring flag (value: `524288`).
`static int` `JAR_SOURCE_ATTACHMENT` Constant describing the jar source attachment flag (value: `262144`).
`protected static String` `VALUE_VERSION_1_0` The version value `1.0`

### Fields inherited from class org.eclipse.ltk.core.refactoring.RefactoringDescriptor

`BREAKING_CHANGE, ID_UNKNOWN, MULTI_CHANGE, NONE, STRUCTURAL_CHANGE, USER_CHANGE`

### Constructor Summary

Constructors
`protected` `JavaRefactoringDescriptor(String id)` Creates a new java refactoring descriptor.
`` `JavaRefactoringDescriptor(String id, String project, String description, String comment, Map<String,String> arguments, int flags)` Creates a new Java refactoring descriptor.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`Refactoring` `createRefactoring(RefactoringStatus status)`
`protected static String` `elementToHandle(String project, IJavaElement element)` Converts the specified element to an input handle.
`protected Map<String,String>` `getArguments()` Returns the argument map of this refactoring descriptor.
`protected static IJavaElement` `handleToElement(String project, String handle)` Converts an input handle back to the corresponding java element.
`protected static IJavaElement` `handleToElement(String project, String handle, boolean check)` Converts an input handle back to the corresponding java element.
`protected static IJavaElement` `handleToElement(WorkingCopyOwner owner, String project, String handle, boolean check)` Converts an input handle back to the corresponding java element.
`protected static IResource` `handleToResource(String project, String handle)` Converts an input handle with the given prefix back to the corresponding resource.
`protected void` `populateArgumentMap()` Populates the refactoring descriptor argument map based on the specified arguments.
`protected static String` `resourceToHandle(String project, IResource resource)` Converts the specified resource to an input handle.
`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.
`RefactoringStatus` `validateDescriptor()` Validates the refactoring descriptor with respect to the constraints imposed by the represented refactoring.

### Methods inherited from class org.eclipse.ltk.core.refactoring.RefactoringDescriptor

`compareTo, createRefactoringContext, equals, getComment, getDescription, getFlags, getID, getProject, getTimeStamp, hashCode, setTimeStamp, toString`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Field Detail

#### ATTRIBUTE_ELEMENT

    protected static final String ATTRIBUTE_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, e.g. element1. The indices of this argument are one-based.

See Also:
  Constant Field Values

#### ATTRIBUTE_INPUT

    protected static final String ATTRIBUTE_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

#### ATTRIBUTE_NAME

    protected static final String ATTRIBUTE_NAME

Predefined argument called `name`.

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

See Also:
  Constant Field Values

#### ATTRIBUTE_REFERENCES

    protected static final String ATTRIBUTE_REFERENCES

Predefined argument called `references`.

This argument should be used to describe whether references to the elements being refactored should be updated as well. The value of this argument is either `"true"` or `"false"`.

See Also:
  Constant Field Values

#### ATTRIBUTE_SELECTION

    protected static final String ATTRIBUTE_SELECTION

Predefined argument called `selection`.

This argument should be used to describe user input selections within a text file. The value of this argument has the format "offset length".

See Also:
  Constant Field Values

#### ATTRIBUTE_VERSION

    protected static final String ATTRIBUTE_VERSION

The version attribute

See Also:
  Constant Field Values

#### JAR_MIGRATION

    public static final int JAR_MIGRATION

Constant describing the jar migration flag (value: `65536`).

Clients should set this flag to indicate that the refactoring can be stored to a JAR file in order to be accessible to the Migrate JAR File refactoring, regardless whether there is a source attachment to the JAR file or not. If this flag is set, `JAR_REFACTORING` should be set as well.

See Also:
  `JAR_REFACTORING`, Constant Field Values

#### JAR_REFACTORING

    public static final int JAR_REFACTORING

Constant describing the jar refactoring flag (value: `524288`).

Clients should set this flag to indicate that the refactoring in principle can be performed on binary elements originating from a JAR file. Refactorings which are able to run on binary elements, but require a correctly configured source attachment to work must set the `JAR_SOURCE_ATTACHMENT` flag as well.

See Also:
  `JAR_SOURCE_ATTACHMENT`, Constant Field Values

#### JAR_SOURCE_ATTACHMENT

    public static final int JAR_SOURCE_ATTACHMENT

Constant describing the jar source attachment flag (value: `262144`).

Clients should set this flag to indicate that the refactoring can be performed on binary elements originating from a JAR file if and only if it has a correctly configured source attachment.

See Also:
  `JAR_REFACTORING`, Constant Field Values

#### VALUE_VERSION_1_0

    protected static final String VALUE_VERSION_1_0

The version value `1.0`

See Also:
  Constant Field Values

#### fArguments

    protected final Map<String,String> fArguments

The argument map (key type: `String`, value type: `String`).

### Constructor Detail

#### JavaRefactoringDescriptor

    protected JavaRefactoringDescriptor(String id)

Creates a new java refactoring descriptor.

Parameters:
  `id` - the unique id of the refactoring

#### JavaRefactoringDescriptor

    public JavaRefactoringDescriptor(String id,
                                     String project,
                                     String description,
                                     String comment,
                                     Map<String,String> arguments,
                                     int flags)

Creates a new Java 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
  `arguments` - a map of arguments that will be persisted and describes all settings for this refactoring
  `flags` - the flags of the refactoring descriptor
Since:
  1.2

### Method Detail

#### elementToHandle

    protected static String elementToHandle(String project,
                                            IJavaElement element)

Converts the specified element to an input handle.

Parameters:
  `project` - the project, or `null` for the workspace
  `element` - the element
Returns:
  a corresponding input handle

#### handleToElement

    protected static IJavaElement handleToElement(String project,
                                                  String handle)

Converts an input handle back to the corresponding java element.

Parameters:
  `project` - the project, or `null` for the workspace
  `handle` - the input handle
Returns:
  the corresponding java element, or `null` if no such element exists

#### handleToElement

    protected static IJavaElement handleToElement(String project,
                                                  String handle,
                                                  boolean check)

Converts an input handle back to the corresponding java element.

Parameters:
  `project` - the project, or `null` for the workspace
  `handle` - the input handle
  `check` - `true` to check for existence of the element, `false` otherwise
Returns:
  the corresponding java element, or `null` if no such element exists

#### handleToElement

    protected static IJavaElement handleToElement(WorkingCopyOwner owner,
                                                  String project,
                                                  String handle,
                                                  boolean check)

Converts an input handle back to the corresponding java element.

Parameters:
  `owner` - the working copy owner
  `project` - the project, or `null` for the workspace
  `handle` - the input handle
  `check` - `true` to check for existence of the element, `false` otherwise
Returns:
  the corresponding java element, or `null` if no such element exists

#### handleToResource

    protected static IResource handleToResource(String project,
                                                String handle)

Converts an input handle with the given prefix back to the corresponding resource.

Parameters:
  `project` - the project, or `null` for the workspace
  `handle` - the input handle
Returns:
  the corresponding resource, or `null` if no such resource exists

#### resourceToHandle

    protected static String resourceToHandle(String project,
                                             IResource resource)

Converts the specified resource to an input handle.

Parameters:
  `project` - the project, or `null` for the workspace
  `resource` - the resource
Returns:
  the input handle

#### createRefactoring

    public Refactoring createRefactoring(RefactoringStatus status)
                                  throws CoreException

Specified by:
  `createRefactoring` in class `RefactoringDescriptor`
Throws:
  `CoreException`

#### getArguments

    protected Map<String,String> getArguments()

Returns the argument map of this refactoring descriptor.

The returned map is a copy of the argument map. Modifying the result does not change the refactoring descriptor itself.

Note: This API must not be extended or reimplemented and should not be called from outside the refactoring framework.

Returns:
  the argument map (key type: `String`, value type: `String`)

#### populateArgumentMap

    protected void populateArgumentMap()

Populates the refactoring descriptor argument map based on the specified arguments. Subclasses should extend and add their arguments to `fArguments`.

#### setComment

    public void setComment(String comment)

Sets the details comment of this refactoring.

This information is used in the user interface to show additional details about the performed refactoring. The default is to use no details comment.

Overrides:
  `setComment` in class `RefactoringDescriptor`
Parameters:
  `comment` - the details comment to set, or `null` to set no details comment
See Also:
  `RefactoringDescriptor.getComment()`

#### setDescription

    public void setDescription(String description)

Sets the description of this refactoring.

This information is used to label a refactoring in the user interface. The default is an unspecified, but legal description.

Overrides:
  `setDescription` in class `RefactoringDescriptor`
Parameters:
  `description` - the non-empty description of the refactoring to set
See Also:
  `RefactoringDescriptor.getDescription()`

#### setFlags

    public void setFlags(int flags)

Sets the flags of this refactoring.

The default is `RefactoringDescriptor.STRUCTURAL_CHANGE | RefactoringDescriptor.MULTI_CHANGE`, unless overridden by a concrete subclass. Clients may use refactoring flags to indicate special capabilities of Java refactorings.

Overrides:
  `setFlags` in class `RefactoringDescriptor`
Parameters:
  `flags` - the flags to set, or `RefactoringDescriptor.NONE` to clear the flags
See Also:
  `RefactoringDescriptor.getFlags()`, `RefactoringDescriptor.NONE`, `RefactoringDescriptor.STRUCTURAL_CHANGE`, `RefactoringDescriptor.BREAKING_CHANGE`, `RefactoringDescriptor.MULTI_CHANGE`, `JAR_MIGRATION`, `JAR_REFACTORING`, `JAR_SOURCE_ATTACHMENT`

#### setProject

    public void setProject(String project)

Sets the project name of this refactoring.

The default is to associate the refactoring with the workspace. Subclasses should call this method with the project name associated with the refactoring's input elements, if available.

Overrides:
  `setProject` in class `RefactoringDescriptor`
Parameters:
  `project` - the non-empty project name to set, or `null` for the workspace
See Also:
  `RefactoringDescriptor.getProject()`

#### validateDescriptor

    public RefactoringStatus validateDescriptor()

Validates the refactoring descriptor with respect to the constraints imposed by the represented refactoring.

Clients must call this method to verify that all arguments have been correctly set and that they satisfy the constraints imposed by specific refactorings. Returning a refactoring status of severity `RefactoringStatus.FATAL` indicates that the refactoring descriptor cannot be used to create a refactoring instance.

Returns:
  a refactoring status describing the outcome of the validation