RefactoringContribution


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ltk.core.refactoring;
12  
13  import java.util.Collections  ;
14  import java.util.Map  ;
15  
16  import org.eclipse.ltk.internal.core.refactoring.history.DefaultRefactoringDescriptor;
17  import org.eclipse.ltk.internal.core.refactoring.history.RefactoringContributionManager;
18  
19  /**
20   * Partial implementation of refactoring contribution objects which are capable
21   * of creating refactoring descriptors or refactoring arguments.
22   * <p>
23   * Clients which would like to add refactoring history and refactoring scripting
24   * support to a refactoring are required to register a subclass of
25   * {@link RefactoringContribution} with the extension point
26   * <code>org.eclipse.ltk.core.refactoring.refactoringContributions</code> to
27   * participate in the refactoring services. Refactoring contributions are
28   * stateless objects. They are instantiated on demand by the refactoring
29   * framework in the following cases:
30   * <ul>
31   * <li> When a refactoring script is executed, the refactoring framework
32   * retrieves a corresponding refactoring contribution for each refactoring
33   * persisted in the script and calls
34   * {@link #createDescriptor(String, String, String, String, Map, int)} with the
35   * appropriate arguments read from the refactoring script to obtain a
36   * language-specific refactoring descriptor. This refactoring descriptor is then
37   * used to dynamically construct the corresponding refactoring object and to
38   * initialize the refactoring object afterwards. The returned refactoring object
39   * is completely initialized and ready to be executed, ie. by
40   * {@link PerformRefactoringOperation}. </li>
41   * <li> After a refactoring has been executed, the refactoring framework stores
42   * the returned refactoring descriptor into the global refactoring history.
43   * During serialization of the descriptor, the refactoring framework calls
44   * {@link #retrieveArgumentMap(RefactoringDescriptor)} of the refactoring
45   * contribution associated with the executed refactoring to obtain a neutral
46   * key-value representation of the state of the language-specific refactoring
47   * descriptor. </li>
48   * </ul>
49   * </p>
50   * Refactorings for which a refactoring contribution has been registered should
51   * also return a {@link RefactoringDescriptor} during change generation (ie.
52   * returning a change object whose {@link Change#getDescriptor()} method has
53   * been implemented to return a {@link RefactoringChangeDescriptor}
54   * encapsulating {@link RefactoringDescriptor}.
55   * </p>
56   * <p>
57   * Since 3.3, refactoring contributions may serve also as a uniform API to
58   * expose language-specific refactorings. Clients wishing to provide
59   * customizable refactoring descriptors may reimplement the method
60   * {@link #createDescriptor()}.
61   * </p>
62   * Note: Clients which extend this class are required to reimplement the method
63   * {@link #retrieveArgumentMap(RefactoringDescriptor)} in subclasses to capture
64   * the state of a language-specific refactoring descriptor in a neutral
65   * key-value representation used by the refactoring framework. The default
66   * implementation in this class only handles refactoring descriptors associated
67   * with refactorings for which no corresponding refactoring contribution has
68   * been registered.
69   * </p>
70   * 
71   * @since 3.2
72   */
73  public abstract class RefactoringContribution {
74  
75      /**
76       * Creates a new customizable refactoring descriptor initialized with its
77       * default values.
78       * <p>
79       * This method may be reimplemented to return a language-specified
80       * refactoring descriptor which can be initialized using language-specific
81       * features. Refactoring tool providers may reimplement this method to
82       * provide a uniform API to expose refactoring functionality in the form of
83       * refactoring descriptors.
84       * </p>
85       * <p>
86       * Callers of this method are supposed to cast the resulting refactoring
87       * descriptor to the corresponding language-specific refactoring descriptor
88       * provided by the API of the refactoring tooling provider.
89       * </p>
90       * <p>
91       * Note: this method is supposed to be reimplemented by clients wishing to
92       * provide customizable refactoring descriptors.
93       * </p>
94       * 
95       * @return the refactoring descriptor, or <code>null</code> if the
96       *         refactoring represented by this contribution does not expose
97       *         customizable refactoring descriptors
98       * 
99       * @see #createDescriptor(String, String, String, String, Map, int)
100      * 
101      * @since 3.3
102      */
103     public RefactoringDescriptor createDescriptor() {
104         return null;
105     }
106 
107     /**
108      * Creates a new refactoring descriptor initialized with the values provided
109      * by the arguments of this method.
110      * <p>
111      * This method is used by the refactoring framework to create a
112      * language-specific refactoring descriptor representing the refactoring
113      * instance corresponding to the specified arguments. Implementations of
114      * this method must never return <code>null</code>. The refactoring
115      * framework guarantees that this method is only called with <code>id</code>
116      * values for which the refactoring contribution has been registered with
117      * the extension point.
118      * </p>
119      * 
120      * @param id
121      *            the unique id of the refactoring
122      * @param project
123      *            the non-empty name of the project associated with this
124      *            refactoring, or <code>null</code> for a workspace
125      *            refactoring
126      * @param description
127      *            a non-empty human-readable description of the particular
128      *            refactoring instance
129      * @param comment
130      *            the comment associated with the refactoring, or
131      *            <code>null</code> for no comment
132      * @param arguments
133      *            the argument map (element type: &lt;String, String&gt;). The
134      *            keys of the arguments are required to be non-empty strings
135      *            which must not contain spaces. The values must be non-empty
136      *            strings
137      * @param flags
138      *            the flags of the refactoring descriptor
139      * @return the refactoring descriptor
140      * 
141      * @see #retrieveArgumentMap(RefactoringDescriptor)
142      */
143     public abstract RefactoringDescriptor createDescriptor(String   id, String   project, String   description, String   comment, Map   arguments, int flags);
144 
145     /**
146      * Returns the refactoring id for which this refactoring contribution has
147      * been registered with the extension point. Implementations of
148      * {@link #createDescriptor()} may use this method to initialize the
149      * resulting refactoring descriptor with the id of this refactoring
150      * contribution.
151      * <p>
152      * Note: this method is not intended to be extended or reimplemented by
153      * clients.
154      * </p>
155      * 
156      * @return the unique id of the refactoring
157      * 
158      * @since 3.3
159      */
160     public String   getId() {
161         return RefactoringContributionManager.getInstance().getRefactoringId(this);
162     }
163 
164     /**
165      * Retrieves the argument map of the specified refactoring descriptor.
166      * <p>
167      * This method is used by the refactoring framework to obtain
168      * refactoring-specific arguments provided by the refactoring descriptor.
169      * These are the arguments which are specific to certain refactoring
170      * instances, and correspond to the argument map which has been passed to
171      * {@link #createDescriptor(String, String, String, String, Map, int)} upon
172      * creation of the refactoring descriptor.
173      * </p>
174      * <p>
175      * The returned argument map (element type: &lt;String, String&gt;) must
176      * satisfy the following conditions:
177      * <ul>
178      * <li>The keys of the arguments are required to be non-empty strings which
179      * must not contain spaces. </li>
180      * <li>The values must be non-empty</li>
181      * strings
182      * </ul>
183      * </p>
184      * <p>
185      * Note: Subclasses must extend this method to provide more specific
186      * implementation in order to let the refactoring framework retrieve the
187      * argument map from language-specific refactoring descriptors.
188      * Implementations of this method must never return <code>null</code>.
189      * The refactoring framework guarantees that this method is only called for
190      * refactoring descriptors which have been obtained by a previous call to
191      * {@link #createDescriptor(String, String, String, String, Map, int)}.
192      * </p>
193      * 
194      * @param descriptor
195      *            the refactoring descriptor to retrieve its argument map
196      * @return the argument map of the specified refactoring descriptor
197      * 
198      * @see #createDescriptor(String, String, String, String, Map, int)
199      */
200     public Map   retrieveArgumentMap(final RefactoringDescriptor descriptor) {
201         if (descriptor instanceof DefaultRefactoringDescriptor) {
202             final DefaultRefactoringDescriptor extended= (DefaultRefactoringDescriptor) descriptor;
203             return extended.getArguments();
204         }
205         return Collections.EMPTY_MAP;
206     }
207 }
208
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags