CompilationUnitSorter


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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   *     Alex Blewitt - alex_blewitt@yahoo.com https://bugs.eclipse.org/bugs/show_bug.cgi?id=171066
11   *******************************************************************************/
12  
13  package org.eclipse.jdt.core.util;
14  
15  import java.util.Comparator  ;
16  
17  import org.eclipse.core.runtime.IProgressMonitor;
18  import org.eclipse.jdt.core.ICompilationUnit;
19  import org.eclipse.jdt.core.IJavaElement;
20  import org.eclipse.jdt.core.JavaModelException;
21  import org.eclipse.jdt.core.dom.AST;
22  import org.eclipse.jdt.core.dom.CompilationUnit;
23  import org.eclipse.jdt.internal.core.SortElementsOperation;
24  import org.eclipse.text.edits.TextEdit;
25  import org.eclipse.text.edits.TextEditGroup;
26  
27  /**
28   * Operation for sorting members within a compilation unit.
29   * <p>
30   * This class provides all functionality via static members; it is not
31   * intended to be instantiated or subclassed.
32   * </p>
33   * 
34   * @since 2.1
35   */
36  public final class CompilationUnitSorter {
37      
38      /**
39       * Private constructor to prevent instantiation.
40       */
41      private CompilationUnitSorter() {
42          // Not instantiable
43      } 
44      
45      /**
46       * @deprecated marking deprecated as it is using deprecated code
47       */
48      private static void checkASTLevel(int level) {
49          switch (level) {
50          case AST.JLS2 :
51          case AST.JLS3 :
52              break;
53          default :
54              throw new IllegalArgumentException  ();
55          }
56      }
57  
58      /**
59       * Name of auxillary property whose value can be used to determine the
60       * original relative order of two body declarations. This allows a
61       * comparator to preserve the relative positions of certain kinds of
62       * body declarations when required.
63       * <p>
64       * All body declarations passed to the comparator's <code>compare</code>
65       * method by <code>CompilationUnitSorter.sort</code> carry an
66       * Integer-valued property. The body declaration with the lower value
67       * comes before the one with the higher value. The exact numeric value
68       * of these properties is unspecified.
69       * </p>
70       * <p>
71       * Example usage:
72       * <pre>
73       * BodyDeclaration b1 = (BodyDeclaration) object1;
74       * BodyDeclaration b2 = (BodyDeclaration) object2;
75       * Integer i1 = (Integer) b1.getProperty(RELATIVE_ORDER);
76       * Integer i2 = (Integer) b2.getProperty(RELATIVE_ORDER);
77       * return i1.intValue() - i2.intValue(); // preserve original order
78       * </pre>
79       * </p>
80       * 
81       * @see #sort(ICompilationUnit, int[], Comparator, int, IProgressMonitor)
82       * @see org.eclipse.jdt.core.dom.BodyDeclaration
83       */
84      public static final String   RELATIVE_ORDER = "relativeOrder"; //$NON-NLS-1$
85  
86      /**
87       * Reorders the declarations in the given compilation unit according to
88       * JLS2 rules. The caller is
89       * responsible for arranging in advance that the given compilation unit is
90       * a working copy, and for saving the changes afterwards.
91       * <p>
92       * <b>Note:</b> Reordering the members within a type declaration might be
93       * more than a cosmetic change and could have potentially serious
94       * repercussions. Firstly, the order in which the fields of a type are
95       * initialized is significant in the Java language; reordering fields
96       * and initializers may result in compilation errors or change the execution
97       * behavior of the code. Secondly, reordering a class's members may affect
98       * how its instances are serialized. This operation should therefore be used
99       * with caution and due concern for potential negative side effects.
100      * </p>
101      * <p>
102      * The optional <code>positions</code> array contains a non-decreasing 
103      * ordered list of character-based source positions within the compilation
104      * unit's source code string. Upon return from this method, the positions in
105      * the array reflect the corresponding new locations in the modified source
106      * code string. Note that this operation modifies the given array in place.
107      * </p>
108      * <p>
109      * The <code>compare</code> method of the given comparator is passed pairs
110      * of JLS2 AST body declarations (subclasses of <code>BodyDeclaration</code>) 
111      * representing body declarations at the same level. The comparator is
112      * called on body declarations of nested classes, including anonymous and
113      * local classes, but always at the same level. Clients need to provide
114      * a comparator implementation (there is no standard comparator). The
115      * <code>RELATIVE_ORDER</code> property attached to these AST nodes afforts
116      * the comparator a way to preserve the original relative order.
117      * </p>
118      * <p>
119      * The body declarations passed as parameters to the comparator
120      * always carry at least the following minimal signature information:
121      * <br>
122      * <table border="1" width="80%" cellpadding="5">
123      *    <tr>
124      *      <td width="20%"><code>TypeDeclaration</code></td>
125      *      <td width="50%"><code>modifiers, isInterface, name, superclass,
126      *        superInterfaces<br>
127      *        RELATIVE_ORDER property</code></td>
128      *    </tr>
129      *    <tr>
130      *      <td width="20%"><code>FieldDeclaration</code></td>
131      *      <td width="50%"><code>modifiers, type, fragments
132      *        (VariableDeclarationFragments
133      *        with name only)<br>
134      *        RELATIVE_ORDER property</code></td>
135      *    </tr>
136      *    <tr>
137      *      <td width="20%"><code>MethodDeclaration</code></td>
138      *      <td width="50%"><code>modifiers, isConstructor, returnType, name,
139      *        parameters
140      *        (SingleVariableDeclarations with name and type only),
141      *        thrownExceptions<br>
142      *        RELATIVE_ORDER property</code></td>
143      *    </tr>
144      *    <tr>
145      *      <td width="20%"><code>Initializer</code></td>
146      *      <td width="50%"><code>modifiers<br>
147      *        RELATIVE_ORDER property</code></td>
148      *    </tr>
149      * </table>
150      * Clients should not rely on the AST nodes being properly parented or on
151      * having source range information. (Future releases may provide options
152      * for requesting additional information like source positions, full ASTs,
153      * non-recursive sorting, etc.)
154      * </p>
155      *
156      * @param compilationUnit the given compilation unit, which must be a 
157      * working copy
158      * @param positions an array of source positions to map, or 
159      * <code>null</code> if none. If supplied, the positions must 
160      * character-based source positions within the original source code for
161      * the given compilation unit, arranged in non-decreasing order.
162      * The array is updated in place when this method returns to reflect the
163      * corresponding source positions in the permuted source code string
164      * (but not necessarily any longer in non-decreasing order).
165      * @param comparator the comparator capable of ordering 
166      *   <code>BodyDeclaration</code>s; this comparator is passed AST nodes
167      *   from a JLS2 AST
168      * @param options bitwise-or of option flags; <code>0</code> for default
169      * behavior (reserved for future growth)
170      * @param monitor the progress monitor to notify, or <code>null</code> if
171      * none
172      * @exception JavaModelException if the compilation unit could not be
173      * sorted. Reasons include:
174      * <ul>
175      * <li> The given compilation unit does not exist (ELEMENT_DOES_NOT_EXIST)</li>
176      * <li> The given compilation unit is not a working copy (INVALID_ELEMENT_TYPES)</li>
177      * <li> A <code>CoreException</code> occurred while accessing the underlying
178      * resource
179      * </ul>
180      * @exception IllegalArgumentException if the given compilation unit is null
181      * or if the given comparator is null.
182      * @see org.eclipse.jdt.core.dom.BodyDeclaration
183      * @see #RELATIVE_ORDER
184      * @deprecated Clients should port their code to use the new JLS3 AST API and call
185      *    {@link #sort(int, ICompilationUnit, int[], Comparator, int, IProgressMonitor)
186      *    CompilationUnitSorter.sort(AST.JLS3, compilationUnit, positions, comparator, options, monitor)}
187      *    instead of using this method.
188      */
189     public static void sort(ICompilationUnit compilationUnit,
190             int[] positions,
191             Comparator   comparator,
192             int options,
193             IProgressMonitor monitor) throws JavaModelException {
194         sort(AST.JLS2, compilationUnit, positions, comparator, options, monitor);
195     }
196     
197     /**
198      * Reorders the declarations in the given compilation unit according to
199      * the specified AST level. The caller is responsible for arranging in
200      * advance that the given compilation unit is a working copy, and for
201      * saving the changes afterwards.
202      * <p>
203      * <b>Note:</b> Reordering the members within a type declaration might be
204      * more than a cosmetic change and could have potentially serious
205      * repercussions. Firstly, the order in which the fields of a type are
206      * initialized is significant in the Java language; reordering fields
207      * and initializers may result in compilation errors or change the execution
208      * behavior of the code. Secondly, reordering a class's members may affect
209      * how its instances are serialized. This operation should therefore be used
210      * with caution and due concern for potential negative side effects.
211      * </p>
212      * <p>
213      * The optional <code>positions</code> array contains a non-decreasing 
214      * ordered list of character-based source positions within the compilation
215      * unit's source code string. Upon return from this method, the positions in
216      * the array reflect the corresponding new locations in the modified source
217      * code string. Note that this operation modifies the given array in place.
218      * </p>
219      * <p>
220      * The <code>compare</code> method of the given comparator is passed pairs
221      * of body declarations (subclasses of <code>BodyDeclaration</code>) 
222      * representing body declarations at the same level. The nodes are from an
223      * AST of the specified level 
224      * ({@link org.eclipse.jdt.core.dom.ASTParser#newParser(int)}. Clients
225      * will generally specify AST.JLS3 since that will cover all constructs found
226      * in Java 1.0, 1.1, 1.2, 1.3, 1.4, and 1.5 source code.
227      * The comparator is called on body declarations of nested classes, including
228      * anonymous and local classes, but always at the same level. Clients need to provide
229      * a comparator implementation (there is no standard comparator). The
230      * <code>RELATIVE_ORDER</code> property attached to these AST nodes afforts
231      * the comparator a way to preserve the original relative order.
232      * </p>
233      * <p>
234      * The body declarations passed as parameters to the comparator
235      * always carry at least the following minimal signature information:
236      * <br>
237      * <table border="1" width="80%" cellpadding="5">
238      *    <tr>
239      *      <td width="20%"><code>TypeDeclaration</code></td>
240      *      <td width="50%"><code>modifiers, isInterface, name, superclass,
241      *        superInterfaces, typeParameters<br>
242      *        RELATIVE_ORDER property</code></td>
243      *    </tr>
244      *    <tr>
245      *      <td width="20%"><code>FieldDeclaration</code></td>
246      *      <td width="50%"><code>modifiers, type, fragments
247      *        (VariableDeclarationFragments
248      *        with name only)<br>
249      *        RELATIVE_ORDER property</code></td>
250      *    </tr>
251      *    <tr>
252      *      <td width="20%"><code>MethodDeclaration</code></td>
253      *      <td width="50%"><code>modifiers, isConstructor, returnType, name,
254      *        typeParameters, parameters
255      *        (SingleVariableDeclarations with name, type, and modifiers only),
256      *        thrownExceptions<br>
257      *        RELATIVE_ORDER property</code></td>
258      *    </tr>
259      *    <tr>
260      *      <td width="20%"><code>Initializer</code></td>
261      *      <td width="50%"><code>modifiers<br>
262      *        RELATIVE_ORDER property</code></td>
263      *    </tr>
264      *    <tr>
265      *      <td width="20%"><code>AnnotationTypeDeclaration</code></td>
266      *      <td width="50%"><code>modifiers, name<br>
267      *        RELATIVE_ORDER property</code></td>
268      *    </tr>
269      *    <tr>
270      *      <td width="20%"><code>AnnotationTypeMemberDeclaration</code></td>
271      *      <td width="50%"><code>modifiers, name, type, default<br>
272      *        RELATIVE_ORDER property</code></td>
273      *    </tr>
274      *    <tr>
275      *      <td width="20%"><code>EnumDeclaration</code></td>
276      *      <td width="50%"><code>modifiers, name, superInterfaces<br>
277      *        RELATIVE_ORDER property</code></td>
278      *    </tr>
279      *    <tr>
280      *      <td width="20%"><code>EnumConstantDeclaration</code></td>
281      *      <td width="50%"><code>modifiers, name, arguments<br>
282      *        RELATIVE_ORDER property</code></td>
283      *    </tr>
284      * </table>
285      * Clients should not rely on the AST nodes being properly parented or on
286      * having source range information. (Future releases may provide options
287      * for requesting additional information like source positions, full ASTs,
288      * non-recursive sorting, etc.)
289      * </p>
290      *
291      * @param level the AST level; one of the AST LEVEL constants
292      * @param compilationUnit the given compilation unit, which must be a 
293      * working copy
294      * @param positions an array of source positions to map, or 
295      * <code>null</code> if none. If supplied, the positions must 
296      * character-based source positions within the original source code for
297      * the given compilation unit, arranged in non-decreasing order.
298      * The array is updated in place when this method returns to reflect the
299      * corresponding source positions in the permuted source code string
300      * (but not necessarily any longer in non-decreasing order).
301      * @param comparator the comparator capable of ordering 
302      *   <code>BodyDeclaration</code>s; this comparator is passed AST nodes
303      *   from an AST of the specified AST level
304      * @param options bitwise-or of option flags; <code>0</code> for default
305      * behavior (reserved for future growth)
306      * @param monitor the progress monitor to notify, or <code>null</code> if
307      * none
308      * @exception JavaModelException if the compilation unit could not be
309      * sorted. Reasons include:
310      * <ul>
311      * <li> The given compilation unit does not exist (ELEMENT_DOES_NOT_EXIST)</li>
312      * <li> The given compilation unit is not a working copy (INVALID_ELEMENT_TYPES)</li>
313      * <li> A <code>CoreException</code> occurred while accessing the underlying
314      * resource
315      * </ul>
316      * @exception IllegalArgumentException if the given compilation unit is null
317      * or if the given comparator is null, or if <code>level</code> is not one of
318      * the AST JLS level constants.
319      * @see org.eclipse.jdt.core.dom.BodyDeclaration
320      * @see #RELATIVE_ORDER
321      * @since 3.1
322      */
323     public static void sort(int level, ICompilationUnit compilationUnit,
324             int[] positions,
325             Comparator   comparator,
326             int options,
327             IProgressMonitor monitor) throws JavaModelException {
328         if (compilationUnit == null || comparator == null) {
329             throw new IllegalArgumentException  ();
330         }
331         checkASTLevel(level);
332         ICompilationUnit[] compilationUnits = new ICompilationUnit[] { compilationUnit };
333         SortElementsOperation operation = new SortElementsOperation(level, compilationUnits, positions, comparator);
334         operation.runOperation(monitor);
335     }
336     
337     /**
338      * Reorders the declarations in the given compilation unit according to the
339      * specified comparator. The caller is responsible for arranging in advance
340      * that the given compilation unit is a working copy, and for applying the
341      * returned TextEdit afterwards.
342      * <p>
343      * <b>Note:</b> Reordering the members within a type declaration might be
344      * more than a cosmetic change and could have potentially serious
345      * repercussions. Firstly, the order in which the fields of a type are
346      * initialized is significant in the Java language; reordering fields and
347      * initializers may result in compilation errors or change the execution
348      * behavior of the code. Secondly, reordering a class's members may affect
349      * how its instances are serialized. This operation should therefore be used
350      * with caution and due concern for potential negative side effects.
351      * </p>
352      * <p>
353      * The <code>compare</code> method of the given comparator is passed pairs
354      * of body declarations (subclasses of <code>BodyDeclaration</code>)
355      * representing body declarations at the same level. 
356      * The comparator is called on body declarations of nested classes,
357      * including anonymous and local classes, but always at the same level.
358      * Clients need to provide a comparator implementation (there is no standard
359      * comparator). The <code>RELATIVE_ORDER</code> property attached to these
360      * AST nodes affords the comparator a way to preserve the original relative
361      * order.
362      * </p>
363      * <p>
364      * The body declarations passed as parameters to the comparator always carry
365      * at least the following minimal signature information: <br>
366      * <table border="1" width="80%" cellpadding="5">
367      * <tr>
368      * <td width="20%"><code>TypeDeclaration</code></td>
369      * <td width="50%"><code>modifiers, isInterface, name, superclass,
370      *        superInterfaces, typeParameters<br>
371      *        RELATIVE_ORDER property</code></td>
372      * </tr>
373      * <tr>
374      * <td width="20%"><code>FieldDeclaration</code></td>
375      * <td width="50%"><code>modifiers, type, fragments
376      *        (VariableDeclarationFragments
377      *        with name only)<br>
378      *        RELATIVE_ORDER property</code></td>
379      * </tr>
380      * <tr>
381      * <td width="20%"><code>MethodDeclaration</code></td>
382      * <td width="50%"><code>modifiers, isConstructor, returnType, name,
383      *        typeParameters, parameters
384      *        (SingleVariableDeclarations with name, type, and modifiers only),
385      *        thrownExceptions<br>
386      *        RELATIVE_ORDER property</code></td>
387      * </tr>
388      * <tr>
389      * <td width="20%"><code>Initializer</code></td>
390      * <td width="50%"><code>modifiers<br>
391      *        RELATIVE_ORDER property</code></td>
392      * </tr>
393      * <tr>
394      * <td width="20%"><code>AnnotationTypeDeclaration</code></td>
395      * <td width="50%"><code>modifiers, name<br>
396      *        RELATIVE_ORDER property</code></td>
397      * </tr>
398      * <tr>
399      * <td width="20%"><code>AnnotationTypeMemberDeclaration</code></td>
400      * <td width="50%"><code>modifiers, name, type, default<br>
401      *        RELATIVE_ORDER property</code></td>
402      * </tr>
403      * <tr>
404      * <td width="20%"><code>EnumDeclaration</code></td>
405      * <td width="50%"><code>modifiers, name, superInterfaces<br>
406      *        RELATIVE_ORDER property</code></td>
407      * </tr>
408      * <tr>
409      * <td width="20%"><code>EnumConstantDeclaration</code></td>
410      * <td width="50%"><code>modifiers, name, arguments<br>
411      *        RELATIVE_ORDER property</code></td>
412      * </tr>
413      * </table>
414      * </p>
415      * 
416      * @param unit
417      *            the CompilationUnit to sort
418      * @param comparator
419      *            the comparator capable of ordering
420      *            <code>BodyDeclaration</code>s; this comparator is passed
421      *            AST nodes from an AST of the specified AST level
422      * @param options
423      *            bitwise-or of option flags; <code>0</code> for default
424      *            behavior (reserved for future growth)
425      * @param group
426      *            the text edit group to use when generating text edits, or <code>null</code>
427      * @param monitor
428      *            the progress monitor to notify, or <code>null</code> if none
429      * @return a TextEdit describing the required edits to do the sort, or <code>null</code> 
430      *            if sorting is not required
431      * @exception JavaModelException
432      *                if the compilation unit could not be sorted. Reasons
433      *                include:
434      *                <ul>
435      *                <li> The given unit was not created from a ICompilationUnit (INVALID_ELEMENT_TYPES)</li>
436      *                </ul>
437      * @exception IllegalArgumentException
438      *                if the given compilation unit is null or if the given
439      *                comparator is null, or if <code>options</code> is not one
440      *                of the supported levels.
441      * @see org.eclipse.jdt.core.dom.BodyDeclaration
442      * @see #RELATIVE_ORDER
443      * @since 3.3
444      */
445     public static TextEdit sort(CompilationUnit unit,
446             Comparator   comparator,
447             int options,
448             TextEditGroup group,
449             IProgressMonitor monitor) throws JavaModelException {
450         if (unit == null || comparator == null) {
451             throw new IllegalArgumentException  ();
452         }
453         SortElementsOperation operation = new SortElementsOperation(AST.JLS3, new IJavaElement[] { unit.getJavaElement() }, null, comparator);
454         return operation.calculateEdit(unit, group);
455     }
456 }
457
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags