Jindent - Java Source Code Formatter http://www.jindent.com
 

previous topic  Previous:  Misc Next:  Separator comments   next topic

title
5.6.1.13 Sorting

title
5.6.1.13.1 Sorter

Use case-sensitive name sorting

Use case-sensitive name sorting

Enables case-sensitive sorting of names for all types of declarations.



Sort type declarations

Sort type declarations

Enables sorting of type declarations.

Disabling keeps the type declaration order from original source codes.

See also... See also: Type declaration sorter tree




Type declaration sorter tree

Type declaration sorter tree

Tree to specify sorting order of type declarations.

Type declarations are:
To change the main order of type declarations just click on a first level element of the tree and move it up or down with the arrow buttons located right.


With this kind of navigation it is possible to gain different declaration orders, for instance:

|                                       
+- Annotation Types                     
+- Enum Constants                       
+- Enums                                
+- Classes                              
+- Interfaces                           

In this example Jindent would at first print all annotation types, then enumeration constants, enumerations with bodies, classes and finally interfaces.

An example result could look like:

enum Counter {                          
    ...                                 
}                                       
                                        
class DummyClass {                      
    ...                                 
}                                       
                                        
class AnotherTest {                     
    ...                                 
}                                       
                                        
public class Test {                     
    ...                                 
}                                       
                                        
interface InterfaceA {                  
    ...                                 


As we can see the first level elements of the sorting tree specify the first level order of type declarations.
In some way this sorting is a special case of 'grouping'. In the example above all type declarations are grouped together (for example: classes). Therefore we call it 'declaration groups'.
To get control about sorting order within these groups just double click on a tree element to get additional sorting options.

Additional sorting options for classes:

|                                       
+- Annotation Types                     
+- Enum Constants                       
+- Enums                                
+- Classes                              
|     +- 1. Sort by Access Modifiers      [x]
|     |     +- public                        
|     |     +- friendly                        
|     |        
|     +- 2. Sort by Annotation Modifier   [x]
|     |     +- Non-Annotated                       
|     |     +- Annotated                        
|     |        
|     +- 3. Sort by Abstract Modifier     [x]
|     |     +- Abstract
|     |     +- Non-Abstract
|     |        
|     +- 4. Sort by Final Modifier        [x]
|     |     +- Final
|     |     +- Non-Final
|     |        
|     +- 5. Sort by Name                  [x]
|     +- 6. Sort by StrictFP Modifier     [ ]
|           +- StrictFP
|           +- Non-SctrictFP
|                                       
+- Interfaces                           

Sorting within each declaration group is controlled by individual 'sorting filters'. Sorting filters are optional (they can be checked or unchecked) and their execution order can be varied to gain different sorting results.
Additionally sorting filters contain attributes which control the filter's behaviour.
To change the execution order of sorting filters and its attributes just click on a tree element and use the arrow buttons again to move this element up or down.

In the sorter tree example above Jindent would use the following algorithm to compare two classes to proceed sorting within the class delcaration group:
  1. If one of two classes has a public modifier then move this class up, if class is friendly then move class down.
  2. If two classes are both public or both friendly then move class without annotations up and class with annotations down.
  3. If two classes have the same modifiers and both have annotations or both have no annotations then move abstract class up and non-abstract class down.
  4. If two classes have the same modifiers, annotations or both are abstract or not abstractthen move final class up and non-final class down.
  5. If two classes still have same modifiers and annotations then compare classes alphabetically by its names.
  6. Sorting by StrictFP Modifier is unchecked, so it has no effect.

After using the described sorting algorithm the previous example looks like:

enum Counter {                          
    ...                                 
}                                       
                                        
public class Test {                     
    ...                                 
}                                       
                                        
class AnotherTest {                     
    ...                                 
}                                       
                                        
class DummyClass {                      
    ...                                 
}                                       
                                        
interface InterfaceA {                  
    ...                                 


At first glance the sorting settings seem to be complicated but actually they are nothing else but a tree which intuitionally describes which sorting priority has to come first and which last. If two declarations have the same sorting characteristics then Jindent uses the next child of tree to proceed deeper comparison. If there is no tree child left and still no satisfying comparision was possible then original order from input source code will be used.

Of course it is not necessary to use all sorting filters. Just check the filters which are desired for your code convention and leave all other filters unchecked.


Please note: If no sorting filter for a specific type declaration is used then Jindent will keep the original order from the input source code within this declaration group. Therefore it is possible to group declaration types without necessarily sorting them among themselves.



Insert separator comments before type declarations

Insert separator comments before type declarations

Inserts separator comments before every type declaration group.

Separator comments introduce different declaration groups with a short comment.
(For definition of 'declaration group' please refer to setting: "Type declaration sorter tree")



Example of inserted separator comments:

                                        
//~--- Class declarations ------------------------
                                        
public class MyClass {                  
    ...                                 
}                                       
                                        
class AnotherClass {                    
    ...                                 
}                                       
                                        
//~--- Interface declarations --------------------
                                        
interface MyInterface {                 
    ...                                 
}                                       
                                        
//~--- Enum declarations -------------------------
                                        
enum Counter {                          
    ...                                 
}                                       

Separator comments always start with the prefix //~ so that Jindent is able to recognize and remove already inserted separator comments from previous Jindent sessions.


See also... See also: Jindent - Settings - Formatter - Java / SQLJ - Sorting - Separator comments




Insert separator comments only between type declarations

Insert separator comments only between type declarations

Inserts separator comments only between declaration groups.

For more details please refer to setting: "Insert separator comments before type declarations"


Example from previous setting description:

public class MyClass {                  
    ...                                 
}                                       
                                        
class AnotherClass {                    
    ...                                 
}                                       
                                        
//~--- Interface declarations --------------------
                                        
interface MyInterface {                 
    ...                                 
}                                       
                                        
//~--- Enum declarations -------------------------
                                        
enum Counter {                          
    ...                                 
}                                       

Separator comment is not inserted before class declaration because there is no other preceding declaration.



Sort within class, interface and enum declarations

Sort within class, interface and enum declarations

Enables sorting within type declarations.

Disabling keeps the internal type declaration order from original source codes.

See also... See also: Within type declaration sorter tree




Within type declaration sorter tree

Within type declaration sorter tree

Tree to specify sorting order of declarations within classes, interfaces and enums.

Elements within type declarations are:
To change the main order of declarations just click on a first level element of the tree and move it up or down with the arrow buttons located right.


With this kind of navigation it is possible to gain different declaration orders, for instance:

|                                       
+- Static Fields                        
+- Static Initializers                  
+- Enum Constants                       
+- Enums                                
+- Fields                               
+- Initializers                         
+- Annotation Types                     
+- Constructors                         
+- Methods                              
+- Inner Classes                        
+- Inner Interfaces                     

In this example Jindent would at first print all static fields, then static initializers, enumeration constants, enumerations with bodies, fields, initializers, annotation types, constructors, methods, inner classes and finally inner interfaces.

An example result could look like:

public class DummyClass {               
                                        
    private static int fieldB;          
    private static int fieldC;          
    private static int fieldA;          
    private static int CONST_1 = 1;     
    private static int CONST_2 = 2;     
                                        
    static {                            
        fieldB = 10;                    
    }                                   
                                        
    private enum Counter { ONE, TWO, THREE };
                                        
    private DummyClass(int i) {         
        ...                             
    }                                   
                                        
    public DummClass() {                
        this(10);                       
    }                                   
                                        
    public void methodC(String s) {     
        ...                             
    }                                   
    public int getB() {                 
        ...                             
    }                                   
    public void methodA(int i) {        
        ...                             
    }                                   
    public int getA() {                 
        ...                             
    }                                   
                                        
    class InnerClass {                  
        ...                             
    }                                   
}                                       


As we can see the first level elements of the sorting tree specify the order of first level declarations.
In some way this sorting is a special case of 'grouping'. In the example above all declarations are grouped together (for example: methods are grouped together). Therefore we call it 'declaration groups'.
To get control about the sorting order within these groups just double click on a tree element to get additional sorting options.

Additional sorting options for methods:

|                                       
+- Static Fields                        
+- Static Initializers                  
+- Enum Constants                       
+- Enums                                
+- Fields                               
+- Initializers                         
+- Annotation Types                     
+- Constructors                         
+- Methods                              
|     +-  1. Sort by Access Modifiers        [x]
|     |      +- public
|     |      +- friendly
|     |      +- protected
|     |      +- private
|     |        
|     +-  2. Sort by Method Type             [x]
|     |      +- Getters
|     |      +- Has Getters
|     |      +- Is Getters
|     |      +- Setters
|     |      +- Ordinary Methods
|     |        
|     +-  3. Sort by Native Modifier         [x]
|     |      +- Native
|     |      +- Non-Native
|     |        
|     +-  4. Sort by Static Modifier         [x]
|     |      +- Static 
|     |      +- Non-Static
|     |        
|     +-  5. Sort by Final Modifier          [x]
|     |      +- Final
|     |      +- Non-Final
|     |        
|     +-  6. Sort by Annotation Modifier     [ ]
|     +-  7. Sort by Abstract Modifier       [ ]
|     +-  8. Sort by Synchronized Modifier   [ ]
|     +-  9. Sort by StrictFP Modifier       [ ]
|     +- 10. Sort by Name                    [x]
|     +- 11. Sort by Parameter Count         [x]
|                                       
+- Inner Classes                        
+- Inner Interfaces                     

Sorting within each declaration group is controlled by individual 'sorting filters'. Sorting filters are optional (they can be checked or unchecked) and their execution order can be varied to gain different sorting results.
Additionally sorting filters contain attributes which control the filter's behaviour.
To change the execution order of sorting filters and its attributes just click on a tree element and use the arrow buttons again to move this element up or down.

In the example above Jindent would use the following algorithm to compare two methods to proceed sorting:
  1. The order of the filter attributes defines the result of a method comparisons.
    In our example methods with modifier public would be put before methods with a friendly modifier, methods with friendly modifier before protected methods and protected methods before private.
  2. If two methods have the same modifiers then the method type is casting.
    In our example getters methods (methods with prefix get) would put before has getter methods (methods with prefix has) and so on...
  3. If two methods have same modifiers and same method type then the methods will be compared by its native modifiers.
  4. If the two methods still do not differ then the comparison will be extended by its static modifier.
  5. Then they will be compared by its final modifiers.
  6. Comparison with annotation modifiers will be skipped, because this filter is unchecked.
  7. Comparison with abstract modifiers will be skipped, because this filter is unchecked.
  8. Comparison with synchronized modifiers will be skipped, because this filter is unchecked.
  9. Comparison with strictfp modifiers will be skipped, because this filter is unchecked.
  10. If all comparisions before still haven't result in an unique distinction then the two methods will be alphabetically compared by its method names.
  11. If there is still not a distinction because the two methods have the same method names, then the final comparison will be done by its paramters.

And after sorting the previous example looks like:

public class DummyClass {               
                                        
    private static int fieldB;          
    private static int fieldC;          
    private static int fieldA;          
    private static int CONST_1 = 1;     
    private static int CONST_2 = 2;     
                                        
    static {                            
        fieldB = 10;                    
    }                                   
                                        
    private enum Counter { ONE, TWO, THREE };
                                        
    private DummyClass(int i) {         
        ...                             
    }                                   
                                        
    public DummClass() {                
        this(10);                       
    }                                   
                                        
    public int getA() {                 
        ...                             
    }                                   
    public int getB() {                 
        ...                             
    }                                   
    public void methodA(int i) {        
        ...                             
    }                                   
    public void methodC(String s) {     
        ...                             
    }                                   
                                        
    class InnerClass {                  
        ...                             
    }                                   
}                                       


Of course it is not necessary to use all sorting filters. Just check the filters which are desired for your code convention and leave all other filters unchecked.


Short note about 'sorting initialized fields':

Initialized fields are static or non-static fields which contain initializers. Even if Jindent is able to sort initialized fields it does not change its relative sorting order. Changing the order of initialzed fields could result in compiler errors.


Example of 'critical' input source code:

public class Demo                       
{                                       
    private int fieldD;                 
    private int fieldB = 10;            
    private int fieldC;                 
    private int fieldA = fieldB;        
                                        
    ...                                 
}                                       


If initialized fields would be sorted by name then the bad result would be:

public class Demo                       
{                                       
    private int fieldA = fieldB;        
    private int fieldB = 10;            
    private int fieldC;                 
    private int fieldD;                 
                                        
    ...                                 
}                                       

And this would cause a compiler error, because field fieldA has an illegal forward reference to fieldB.

For that reason Jindent only sorts initialized fields relatively to other non-initialized fields. Therefore Jindent's output would be:

public class Demo                       
{                                       
    private int fieldB = 10;            
    private int fieldA = fieldB;        
    private int fieldC;                 
    private int fieldD;                 
                                        
    ...                                 
}                                       

Field fieldC and fieldD are sorted correctly but the initialized fields fieldA and fieldB did not changed their relative sorting order.



Insert separator comments before declarations within class, interface and enum declarations

Insert separator comments before declarations within class, interface and enum declarations

Inserts separator comments before every declaration group within classes, interfaces and enums.

Separator comments introduce different declaration groups with a short comment.
(For definition of 'declaration group' please refer to setting: "Within type declaration sorter tree")



Example of inserted separator comments:

public class MyClass {                  
                                        
    //~ static field delcarations -----------------         
                                        
    public static int CONSTANT_1 = 1;   
    public static int CONSTANT_2 = 2;   
                                        
    //~ field delcarations ------------------------
                                        
    private int fieldA;                 
    private int fieldB;                 
                                        
    //~ constructor delcarations ------------------
                                        
    public MyClass() {                  
        ...                             
    }                                   
    public MyClass(int i) {             
        ...                             
    }                                   
                                        
    //~ method delcarations -----------------------
                                        
    public void methodA() {             
        ...                             
    }                                   
    public void methodB() {             
        ...                             
    }                                   
    public void methodC() {             
        ...                             
    }                                   
}                                       

Separator comments always start with the prefix //~ so that Jindent is able to recognize and remove already inserted separator comments from previous Jindent sessions.


See also... See also: Jindent - Settings - Formatter - Java / SQLJ - Sorting - Separator comments




Insert separator comments only between declarations within class, interface and enum declarations

Insert separator comments only between declarations within class, interface and enum declarations

Inserts separator comments only between declaration groups within classes, interfaces and enums.
For more details please refer to setting: "Insert separator comments before declarations within class, interface and enum declarations"


Example from previous setting description:

public class MyClass {                  
                                        
    public static int CONSTANT_1 = 1;   
    public static int CONSTANT_2 = 2;   
                                        
    //~ field delcarations ------------------------
                                        
    private int fieldA;                 
    private int fieldB;                 
                                        
    //~ constructor delcarations ------------------
                                        
    public MyClass() {                  
        ...                             
    }                                   
    public MyClass(int i) {             
        ...                             
    }                                   
                                        
    //~ method delcarations -----------------------
                                        
    public void methodA() {             
        ...                             
    }                                   
    public void methodB() {             
        ...                             
    }                                   
    public void methodC() {             
        ...                             
    }                                   
}                                       

Separator comment is not inserted before static field declaration because there is no other preceding declaration.



Insert separator comments within nested class, interface and enum declarations

Insert separator comments within nested class, interface and enum declarations

Insert separator comments even in nested class, interface and enum declarations.



Insert separator comment in nested classes:

public class MyClass {                  
                                        
    class NestedClass {                 
                                        
        //~ field declarations ---------------
                                        
        int a, b, c;                    
                                        
        //~ constructor declarations ---------
                                        
        NestedClass() {                 
            ...                         
        }                               
                                        
        //~ method declarations --------------
                                        
        public int getA() {             
            ...                         
        }                               
    }                                   
}                                       



Sort import declarations

Sort import declarations

Enables sorting of import declarations.

Disabling keeps import declaration order from original source codes.

See also... See also: Import declaration sorter tree




Import declaration sorter tree

Import declaration sorter tree

Tree to specify sorting order of import declarations.

To get full control about sorting order of import declarations just double click on the import tree element to open all sorting options.

Sorting options for import declarations:

|                                       
+- Imports                              
|     +- 1. Group by Package Names        [x]
|     |     +- java
|     |     +- javax
|     |     +- org
|     |     +- com
|     |            
|     +- 2. Sort by Modifiers             [x]
|     |     +- Static
|     |     +- Non-Static
|     |        
|     +- 3. Sort by Name                  [x]
|     +- 4. Group by Package Membership   [ ]
|     |     +- JDK Packages
|     |     +- Non-JDK Packages                
|     |        

Sorting of import declarations is controlled by 'sorting filters'. Sorting filters are optional (they can be checked or unchecked) and their execution order can be varied to gain different sorting results.
Additionally sorting filters contain attributes which control the filter's behaviour.
To change the execution order of sorting filters and its attributes just click on a tree element and use the arrow buttons again to move this element up or down.

In the example above Jindent would use the following algorithm to compare two import declarations to proceed sorting:
  1. First all import statements will be grouped by their package names, as declared in the order in the grouping tree.
  2. Then if one of two import declarations within a group contains a static token then the import will be moved up, and if the import does not contain a static token then the import will be moved down.
  3. Finally the imports will be sorted by their names inside the new group built up by the package name and static/non-static grouping.
  4. The last filter 'Group by Package Membership' is deprecated, because its behaviour can be achieved by using the 'Group by Package Names' filter.

To see how the algorithm works, we assume the following original input source code:

package myPackage;                      
                                        
                                        
import java.awt.peer.CheckboxMenuItemPeer;
import java.awt.event.*;                
import java.io.ObjectOutputStream;      
import static aaa.bbb.MyClassA.*;       
import static aaa.bbb.MyClassB.compute; 
import java.io.ObjectInputStream;       
import aaa.bbb.MyClassD;                
import java.io.IOException;             
import static java.lang.Math.max;       
import aaa.bbb.ccc.*;                   
import aaa.bbb.MyClassC;                
import static java.lang.Math.min;       
import java.awt.Color;                  
import java.awt.Font;                   
import javax.swing.JComponent;          
import javax.swing.border.*;            
                                        
public class ClassA {                   
    ...                                 
}                                       

After formatting this example with the algorithm explained above the output looks like:

package myPackage;                      
                                        
import static java.lang.Math.max;       
import static java.lang.Math.min;       
                                        
import java.awt.Color;                  
import java.awt.Font;                   
import java.awt.event.*;                
import java.awt.peer.CheckboxMenuItemPeer;
                                        
import java.io.IOException;             
import java.io.ObjectInputStream;       
import java.io.ObjectOutputStream;      
                                        
import javax.swing.JComponent;          
import javax.swing.border.*;            
                                        
import static aaa.bbb.MyClassA.*;       
import static aaa.bbb.MyClassB.compute; 
                                        
import aaa.bbb.MyClassC;                
import aaa.bbb.MyClassD;                
import aaa.bbb.ccc.*;                   
                                        
                                        
public class ClassA {                   
    ...                                 
}                                       

(Additionally setting "Grouping depth of imported packages" is set to 2, "Blank lines around import declaration" and "Blank lines around static import declaration" are set to 1.)


Of course it is not necessary to use all sorting filters. Just check the filters which are desired for your code convention and leave all other filters unchecked.



Insert separator comments before import declarations

Insert separator comments before import declarations

Inserts separator comments before import declaration groups.

Separator comments introduce different import declaration groups with a short comment. Different groups are in this case import delcarations which belong to JDK packages and import declarations which does not belong to JDK packages.



Example of inserted separator comments:

package myPackage;                      
                                        
                                        
//~ Non JDK imports ------------------------------          
                                        
import static aaa.bbb.MyClassA.*;       
import static aaa.bbb.MyClassB.compute; 
                                        
import aaa.bbb.MyClassC;                
import aaa.bbb.MyClassD;                
import aaa.bbb.ccc.*;                   
                                        
//~ JDK imports ------------------------------          
                                        
import static java.lang.Math.max;       
import static java.lang.Math.min;       
                                        
import java.awt.Color;                  
import java.awt.Font;                   
import java.awt.event.*;                
import java.awt.peer.CheckboxMenuItemPeer;
                                        
import java.io.IOException;             
import java.io.ObjectInputStream;       
import java.io.ObjectOutputStream;      
                                        
import javax.swing.JComponent;          
import javax.swing.border.*;            
                                        
public class ClassA {                   
    ...                                 
}                                       

Separator comments always start with the prefix //~ so that Jindent is able to recognize and remove already inserted separator comments from previous Jindent sessions.


See also... See also: Jindent - Settings - Formatter - Java / SQLJ - Sorting - Separator comments




Insert separator comments only between import declarations

Insert separator comments only between import declarations

Inserts separator comments only between import declaration groups.
For more details please refer to setting: "Insert separator comments before import declarations"


Example:

package myPackage;                      
                                        
                                        
import static aaa.bbb.MyClassA.*;       
import static aaa.bbb.MyClassB.compute; 
                                        
import aaa.bbb.MyClassC;                
import aaa.bbb.MyClassD;                
import aaa.bbb.ccc.*;                   
                                        
//~ JDK imports ------------------------------          
                                        
import static java.lang.Math.max;       
import static java.lang.Math.min;       
                                        
import java.awt.Color;                  
import java.awt.Font;                   
import java.awt.event.*;                
import java.awt.peer.CheckboxMenuItemPeer;
                                        
import java.io.IOException;             
import java.io.ObjectInputStream;       
import java.io.ObjectOutputStream;      
                                        
import javax.swing.JComponent;          
import javax.swing.border.*;            
                                        
public class ClassA {                   
    ...                                 
}                                       

Separator comment is not inserted before first import declaration because there is no other preceding import declaration.



Grouping depth of imported packages

Grouping depth of imported packages

Specifies grouping depth (related to packages) of import declarations.


Set grouping depth to 2:

package myPackage;                      
                                        
                                        
import aaa.bbb.MyClassC;                
import aaa.bbb.MyClassD;                
import aaa.bbb.ccc.*;                   
                                        
import java.awt.Color;                  
import java.awt.Font;                   
import java.awt.event.*;                
import java.awt.peer.CheckboxMenuItemPeer;
                                        
import java.io.IOException;             
import java.io.ObjectInputStream;       
import java.io.ObjectOutputStream;      
                                        
import javax.swing.JComponent;          
import javax.swing.border.*;            
                                        
public class ClassA {                   
    ...                                 
}                                       

In this example setting "Blank lines around import declaration" is set to 1.


Set grouping depth to 3:

package myPackage;                      
                                        
                                        
import aaa.bbb.MyClassC;                
import aaa.bbb.MyClassD;                
                                        
import aaa.bbb.ccc.*;                   
                                        
import java.awt.Color;                  
import java.awt.Font;                   
                                        
import java.awt.event.*;                
                                        
import java.awt.peer.CheckboxMenuItemPeer;
                                        
import java.io.IOException;             
import java.io.ObjectInputStream;       
import java.io.ObjectOutputStream;      
                                        
import javax.swing.JComponent;          
                                        
import javax.swing.border.*;            
                                        
public class ClassA {                   
    ...                                 
}                                       


Set grouping depth to 1:

package myPackage;                      
                                        
                                        
import aaa.bbb.MyClassC;                
import aaa.bbb.MyClassD;                
import aaa.bbb.ccc.*;                   
                                        
import java.awt.Color;                  
import java.awt.Font;                   
import java.awt.event.*;                
import java.awt.peer.CheckboxMenuItemPeer;          
import java.io.IOException;             
import java.io.ObjectInputStream;       
import java.io.ObjectOutputStream;      
                                        
import javax.swing.JComponent;          
import javax.swing.border.*;            
                                        
public class ClassA {                   
    ...                                 
}                                       

See also... See also: Blank lines around import declaration , Blank lines around static import declaration




Blank lines around import declaration

Blank lines around import declaration

Inserts blank lines around import declaration groups.

Import declaration groups will be build by setting: "Grouping depth of imported packages"

See also... See also: Grouping depth of imported packages




Blank lines around static import declaration

Blank lines around static import declaration

Inserts blank lines around static import declaration groups.

Import declaration groups will be build by setting: "Grouping depth of imported packages"

See also... See also: Grouping depth of imported packages