[Skip to content]
TRIEMAX Software
You are here: Home > Products > Jalopy >

### 2.6.6. Sorting

Lets you control the sorting settings.

#### 2.6.6.1. Declarations

Lets you control the sorting of the main declaration elements of Java compilation units: classes, interfaces, enums, annotations, fields, initializers, constructors and methods.

Figure 2.45. Sorting Declarations settings page

##### 2.6.6.1.1. General

###### Sort class elements

Enables or disables the sorting of declaration elements. When disabled, the elements appear in their original order. Otherwise they are sorted according to the specified order (see Section 2.6.6.1.2, "Sort Order" below).

##### 2.6.6.1.2. Sort Order

You can specify the order in which static fields/initializers, instance fields, instance initializers, constructor, method, enum, annotation, class and interface declarations and enum constants should appear in source files by selecting an element type and moving it up or down the list.

By default, with sorting enabled, the different declaration elements are grouped together, but within one element type the contained declarations are still placed in their original order. For example all methods will be grouped together, but otherwise the methods appear in their original order. Enable any of the check boxes, if you want to have all members of one type sorted, too.

Use the Configure... button to define the order in which the individual members should appear. A dialog opens that lets you specify the sorting criteria, e.g. modifier or name. You can select what criteria should be used and in what order. Jalopy checks all significant sorting conditions in the specified order until the sorting position of a declaration member could be determined.

For example if you want your methods to be sorted according to their access modifier and names, enable both criteria and disable the others. For two methods Jalopy will first check whether the modifiers are equal. If they differ, the sorting order is already obvious and no further criteria applied. But if they are equal, it will check their names and sort the two methods lexicographically.

Please note that for modifiers you can further refine what modifiers should be significant for sorting and in what order they are tested. Though accessible from different dialogs, the settings for modifier sorting are global and used across all declaration types to achieve a consistent style.

###### 2.6.6.1.2.1. Instance Fields

Figure 2.46. Configure Sorting Order of Fields

For fields, you can specify to sort according to modifier, object type and/or name. Enable the check box for each criteria that should be significant and use the Up and Down buttons to specify the order in which the criteria should be applied.

Example 2.687. Field

    public String aName = "John Doo";

In the above example, the access modifier would be `"public"`, the object type `"String"` and the name `"aName"`.

###### Name

Lets you sort fields according to their names.

Example 2.688. Sort fields by name

    protected Vector aAliases = null;
    private   String aName    = "John Doo";
    public    List   aValues  = new ArrayList();

Please note that in the above example only the name is significant for determining the order to demonstrate the purpose.

###### Object Type

Lets you sort fields according to their object type.

Example 2.689. Sort fields by object type

    public    List   aValues  = new ArrayList();
    private   String aName    = "John Doo";
    protected Vector aAliases = null;

Please note that in the above example only the object type is significant for determining the order to demonstrate the purpose.

###### Modifiers

Lets you sort fields according to their modifiers.

Example 2.690. Sort fields by modifiers

    public    List   aValues  = new ArrayList();
    protected Vector aAliases = null;
    private   String aName    = "John Doo";

Please note that in the above example only the modifiers are significant for determining the order to demonstrate the purpose.

To further refine the way sorting is applied for modifiers, select the "Modifiers" entry, press the Configure... button to define what modifiers should be significant and adjust the order in which testing should be applied.

Configuration for modifiers is explained in detail in Section 2.6.6.1.2.5, "Modifiers".

###### 2.6.6.1.2.2. Constructors

Figure 2.47. Configure Sorting Order of Constructors

Constructors can be sorted by modifier, default constructor, copy constructor and parameter count.

Enable the check box for each criteria that should be significant and use the Up and Down buttons to define the order in which the criteria should be applied.

Example 2.691. Constructor

    private Singleton(int rType) {
        ...
    }

In the above example, the modifier would be `"private"`, and the parameter count `"1"`.

###### Default Constructor

Default constructor means the single parameter-less constructor every class may have. If you want to ensure a specific location for default constructors, check this entry and move it to the desired position.

Example 2.692. Default constructor

    public class Foo {

        protected Foo() {
            ...
        }
    }

###### Copy Constructor

Copy constructors are those constructors that take a single parameter of the same type as the class itself. If you want to ensure a specific location for copy constructors, check this entry and move it to the desired position.

Example 2.693. Copy constructor

    public class Foo {

        protected Foo(Foo rFoo) {
            ...
        }
    }

###### Parameter Count

Lets you sort constructors according to the number of parameters. Those whose number is smaller will be placed above the others.

Example 2.694. Constructors sorted by parameter count

    public class Foo {

        protected Foo() {
            ...
        }

        private Foo(Foo rFoo) {
            ...
        }

        public Foo(int param1, String param2) {
            ...
        }
    }

Please note that in the above example only the parameter count is significant for determining the order to demonstrate the purpose.

###### Modifiers

To further refine the way sorting is applied for modifiers, select the "Modifiers" entry, press the Configure... button to define what modifiers should be significant and adjust the order in which testing should be applied.

Example 2.695. Constructors sorted by modifiers

    public class Foo {

        public Foo(int param1, String param2) {
            ...
        }

        protected Foo() {
            ...
        }

        private Foo(Foo rFoo) {
            ...
        }
    }

Please note that in the above example only the modifiers are significant for determining the order to demonstrate the purpose.

Configuration for modifiers is explained in detail in Section 2.6.6.1.2.5, "Modifiers".

###### 2.6.6.1.2.3. Methods

Figure 2.48. Configure Sorting Order of Methods

For methods, you can specify sorting by modifiers, name, parameter count, Java Bean pattern, regular expression pattern or custom ordering. Enable the check box for each criteria that should be significant and use the Up and Down buttons to specify the order in which the criteria should be applied.

Example 2.696. Method

    public final void setName(String first, String second) {
        ...
    }

In the above example, the access modifier would be `"public final"`, the name `"setName"` and parameter count `"2"`.

To further refine the way sorting is applied for modifiers, select the "Modifiers" entry and press the Configure... button to define what modifiers should be significant and adjust their order.

###### Bean Pattern

Bean pattern refers to the Java Bean specification naming convention that requires accessor and mutator methods to begin with either the set, get or is prefixes.

Figure 2.49. Configure Sorting Order of Java Bean Methods

You can control the order in which Java Bean methods and ordinary methods appear by selecting the entry and press the Configure... button. Adjust the order of the different elements in the list component of the new dialog and press Apply. The "Ordinary method" entry refers to all non-Bean methods.

Group methods with similar names

Normally bean pattern sorting means that all methods of one type (getters, boolean getters, setters, ordinary methods) are grouped together according to the specified order. Enabling this option causes all methods with similar names to be grouped together, i.e. bean methods and ordinary methods may be mixed, but all bean methods for one property stay together.

Similar methods are determined by stripping the bean prefix and comparing the resulting method names. Similar methods are grouped together according to the specified order (getters, boolean getters, setters, ordinary methods).

Since 1.5

Example 2.697. Bean pattern sorting

    public void aaaaaa() {}

    public void bbbbbb() {}

    public void cccccc() {}

    public Object getAaaaaa() {}

    public Object getBbbbbb() {}

    public Object getCccccc() {}

    public boolean isAaaaaa() {}

    public boolean isBbbbbb() {}

    public boolean isCccccc() {}

    public void setAaaaaa() {}

    public void setBbbbbb() {}

    public void setCccccc() {}

Example 2.698. Bean pattern sorting, similar methods grouped

    public void aaaaaa() {}

    public Object getAaaaaa() {}

    public boolean isAaaaaa() {}

    public void setAaaaaa() {}

    public void bbbbbb() {}

    public Object getBbbbbb() {}

    public boolean isBbbbbb() {}

    public void setBbbbbb() {}

    public void cccccc() {}

    public Object getCccccc() {}

    public boolean isCccccc() {}

    public void setCccccc() {}

Keep bean methods together

Grouping similar methods will let you group all bean methods for one property together, but the bean methods are otherwise still mixed with ordinary methods. If you instead prefer to have all> bean methods grouped together, you can enable this option to build one large block with all bean methods.

Since 1.8

Example 2.699. Bean pattern sorting, similar methods grouped

    public void aaaaaa() {}

    public Object getAaaaaa() {}

    public boolean isAaaaaa() {}

    public void setAaaaaa() {}

    public void bbbbbb() {}

    public Object getBbbbbb() {}

    public boolean isBbbbbb() {}

    public void setBbbbbb() {}

    public void cccccc() {}

    public Object getCccccc() {}

    public boolean isCccccc() {}

    public void setCccccc() {}

Example 2.700. Bean pattern sorting, similar methods grouped, bean methods kept together

    public Object getAaaaaa() {}

    public boolean isAaaaaa() {}

    public void setAaaaaa() {}

    public Object getBbbbbb() {}

    public boolean isBbbbbb() {}

    public void setBbbbbb() {}

    public Object getCccccc() {}

    public boolean isCccccc() {}

    public void setCccccc() {}

    public void aaaaaa() {}

    public void bbbbbb() {}

    public void cccccc() {}

###### Regular expression

Lets you define arbitrary regular expressions to match method signatures to specify absolute positions for specific methods.

Figure 2.50. Configure Regular Expression Sorting

Matching is performed against a simplified signature: only the modifiers, return type and method name are used.

Example 2.701. Method declaration

    public boolean equals(Object rOther) {
        ...
    }

The above method declaration would yield the following signature: public boolean equals

Add...

To add a new regular expression, press the Add... button.

Figure 2.51. Add Regular Expression

Enter the regular expression into the Regex textfield and press the Apply... button to apply the addition.

If you want to test the regular expression before you submit it, enter a test string in the String field and press the Test button to perform pattern matching.

Remove

To remove an existing regular expression, select the expression you want to remove and press the Remove button.

Change...

To change an existing regular expression, select the expression you want to change and press the Change... button.

Figure 2.52. Change Regular Expression

Adjust the regular expression in the Regex textfield and press the Apply... button to apply the change.

If you want to test the regular expression before you submit it, enter a test string in the String field and press the Test button to perform pattern matching.

###### Custom Sort Order

As it might not always be sufficient to rely on method signature information alone, developers can take total control over method ordering using special Javadoc tags.

Please note that Javadoc formatting must be enabled for this feature to work!

In order to have methods grouped by purpose, check the Custom entry in the upper list of the dialog, move it to the top and utilize two custom Javadoc tags in your method commentary.

In your method declaration comments, you need to add the Javadoc standalone tag `@jalopy.group` followed by a logical group name. This name can be freely chosen and defines the group a method belongs to.

Example 2.702. Sorting method declarations with @jalopy.group

     /**
      * Returns the value of the Foo property.
      *
      * @jalopy.group  Accessors
      */
      public int getFoo () {
          ...
      }

Then you specify the order of methods with the `@jalopy.group-order` (you can use `@jalopy.group_order` to circumvent a bug in the Sun 1.4.2 Javadoc implementation) in the class or interface Javadoc comment. Simply place all group names defined with `@jalopy.group` tags in the desired order here and all methods will be sorted accordingly.

There is no special requirement on how the logical group names should be written, but it is good practice to separate them by commas.

Example 2.703. Class declaration with @jalopy.group-order

     /**
      * I want methods ordered by value provided in the @jalopy.group tag of
      * each method in this order. If the method doesn't have a @jalopy.group tag,
      * fall back on project defaults.
      *
      * @jalopy.group-order  Constructors,Queries,Accessors
      */
    class Foo {
        ...
    }

This works recursively for all methods of a compilation unit, i.e. for inner classes, Jalopy first checks the inner class declaration comment and if no `@jalopy.group-order` tag can be found, it recursively searches all parent class/interface declarations of the unit.

Please note that all methods that have no custom group information associated are placed below the ones with grouping tags. Within each group the methods are sorted according to the normal criteria (access modifier, name, parameter count).

A group name not only defines the sorting order, but is used for separator comments also (Refer to Section 2.6.6.3, "Comments" for more information on this feature).

Since 1.1

Example 2.704. Custom separator comments

    //~ Queries ------------------------------------------------------------

    /**
      * This method gets object by primary key
      *
      * @param  inConn  db conn
      * @param  inPK    the primary key
      *
      * @jalopy.group  Queries
      */
    public static MyClass getByPK (Connection inConn, Long inPK) {
        ...
    }

    ...

    //~ Accessors ------------------------------------------------------------

    /**
      * This method returns the Name property.
      *
      * @jalopy.group  Accessors
      */
    public String getName (Connection inConn, String inLoginName) {
        ...
    }

###### 2.6.6.1.2.4. Classes, Interfaces, Enums

To sort all class, interfac or enum declarations, you can specify access modifier and name.

Figure 2.53. Configure Sorting Order of Classes, Interfaces and Enums

Example 2.705. Classes/Interfaces

    protected abstract class AbstractPage {
        ...
    }

In the above example, the modifiers would be `"protected abstract"` and the name `"AbstractPage"`.

To further refine the way sorting is applied for access modifiers, select the "Access Modifier" entry, press the Configure... button and define what modifiers should be significant and adjust the order in which testing should be applied.

###### 2.6.6.1.2.5. Modifiers

Lets you define what modifiers should be significant when sorting by modifier and in which order the declarations should be sorted.

Please note that the position of the "Modifiers" entry in the parent dialog, defines whether and when the modifiers are actually used to determine the order of two declarations. E.g. if you want to sort by modifier first, "Modifiers" must be the topmost entry in the parent dialog.

Figure 2.54. Configure Sorting Order of Modifiers

Select the check box of each access modifier that should be used to determine the order of declarations and use the Up and Down buttons to define the order in which the declarations should be sorted.

For example, if you want to place all static methods together above the other ones, you would check the "static" modifier and move it to the top of the list.

Example 2.706. Sort by static modifier first, then access modifier

    class Foo {

        public static void x() {}

        static void y() {}

        public void c() {}

        public void d() {}

        protected void b() {}

        private void a() {}
    }

But if you only want to have the methods sorted by access modifier, just check the four access modifiers and specify the order in which the declarations are to be sorted, e.g. private, package protected, protected and public.

Example 2.707. Sort by access modifier

    class Foo {

        private void a() {}

        static void y() {}

        protected void b() {}

        public void c() {}

        public void d() {}

        public static void x() {}
    }

##### 2.6.6.1.3. Misc

###### Boolean Getter

Lets you define the regular expression that is used to determine what method declarations should be recognized as Boolean Getters.

According to the JavaBeans naming conventions, only method declarations starting with the `is` prefix are Boolean Getters, but it might make sense to lift these restriction. In certain cases it is more reasonable to name methods in a way that better describes its purpose but still treat them as Boolean Getters, like e.g. `canDelete()` or `shouldDelete()`.

Important note: The prefix must be enclosed with matching parentheses! For example, always use something like "^(is|should|can)[A-Z]\w+" rather than "^is|should|can[A-Z]\w+".

Since 1.1

#### 2.6.6.2. Modifiers

Controls the sorting of declaration modifiers.

Figure 2.55. Sorting Modifiers settings page

##### 2.6.6.2.1. General

###### Sort modifiers

Enables or disables the sorting of access modifiers. When disabled, the modifiers appear in their original order. Otherwise they are sorted according to the specified order (see below).

##### 2.6.6.2.2. Sort Order

Lets you specify the order in which the individual modifiers should appear. Select an entry in the list and use the Up and Down buttons to move it to the desired location.

The list contains the different available Java modifiers as of J2SE 5.0. The `@annotation` entry represents marker annotations.

Example 2.708. Marker annotation placed before public modifier

    @Preliminary public class TimeTravel {
        ...
    }

Example 2.709. Marker annotation placed after public modifier

    public @Preliminary class TimeTravel {
        ...
    }

Please note that normal annotations and single-member annotations are always printed before all other modifiers!

Example 2.710. Normal annotation

    @RequestForEnhancement(
        id       = 2868724,
        synopsis = "Provide time-travel functionality",
        engineer = "Mr. Peabody",
        date     = "4/1/2004"
    )
    public static void travelThroughTime(Date destination) {
        ...
    }

Example 2.711. Single-member annotation

    @Copyright("2002 Yoyodyne Propulsion Systems, Inc., All rights reserved.")
    public class OscillationOverthruster {
        ...
    }

#### 2.6.6.3. Comments

Lets you control the behavior of the separator comments. When the sorting of class elements is enabled, separator comments may be inserted before every element section to make it easier to identify the different parts of a source file.

A separator comment usually starts with a leading `//~` followed by the specified description text of a section and a certain number of fill characters to take up the rest of the space. But the style of the comments is fully configurable as well.

Example 2.712. Separator comment

    //~ Methods ------------------------------------------------------------------

Figure 2.56. Comments Separator settings page

##### 2.6.6.3.1. Insert

Controls when separator comments should be inserted.

###### Between sections

Enables the insertion of separator comments between the different code sections of a compilation unit. You can control the appearance of the comments as described in Section 2.6.6.3.2, "Separator Comment Descriptions" and Section 2.6.6.3.3, "Separator Comment Style".

Example 2.713. Separator comments

    public class Foo {

        //~ Static fields/initializers ---------------------------------------

        static final String LABELED_BY_PROPERTY = "labeledBy";

        //~ Instance fields --------------------------------------------------

        private Icon defaultIcon = null;

        //~ Constructors -----------------------------------------------------

        public Foo(String text, Icon icon) {
            ...
        }

        public Foo(String text) {
            ...
        }

        //~ Methods ----------------------------------------------------------

        public Icon getDisabledIcon() {
            ...
        }

        public Icon getIcon() {
            ...
        }

        //~ Inner Classes ----------------------------------------------------

        protected class FooContainer {
          ...
        }
    }

Please note that this option requires the "Sort class elements" option to be enabled in order to take effect!

###### Between sections of inner classes

The insertion of separator comments for inner classes/interfaces may lead to confusion, therefore you can control it here separately.

Example 2.714. Separator comments

    public class Foo {

        //~ Static fields/initializers -----------------------------------

        static final String LABELED_BY_PROPERTY = "labeledBy";

        //~ Instance fields ----------------------------------------------

        private Icon defaultIcon = null;

        //~ Constructors -------------------------------------------------

        public Foo(String text, Icon icon) {
            ...
        }

        public Foo(String text) {
            ...
        }

        //~ Methods ------------------------------------------------------

        public Icon getDisabledIcon() {
            ...
        }

        public Icon getIcon() {
            ...
        }

        //~ Inner Classes ------------------------------------------------

        protected class FooContainer {

            public Component getParent() {
                ...
            }

            //~ Methods --------------------------------------------------

            public int getComponentCount() {
                ...
            }
        }
    }

Please note that this option requires the "Sort class elements" option to be enabled in order to take effect!

###### Between methods

When enabled, separator comments are inserted between method declarations.

Since 1.3

Example 2.715. Method comment separator

    /**
     * Returns the value of the disabledIcon property if it's been set
     *
     * @return The value of the disabledIcon property.
     */
    public Icon getDisabledIcon() {
        ...
    }

    //~ ----------------------------------------------------------------

    /**
     * Return the keycode that indicates a mnemonic key.
     *
     * @return int value for the mnemonic key
     */
    public int getDisplayedMnemonic() {
        ...
    }

Please note that this option requires the "Sort class elements" option to be enabled in order to take effect!

###### Between methods of inner classes

When enabled, separator comments are inserted between method declarations of inner classes.

Since 1.7

Example 2.716. Method comment separator of inner classes

    public class Foo {

        ...

        static class Item {

            /**
             * Returns the value of the disabledIcon property if it's been
             * set
             *
             * @return The value of the disabledIcon property.
             */
            public Icon getDisabledIcon() {
                ...
            }

            //~ //////////////////////////////////////////////////////////

            /**
             * Return the keycode that indicates a mnemonic key.
             *
             * @return int value for the mnemonic key
             */
            public int getDisplayedMnemonic() {
                ...
            }
        }
    }

Please note that this option requires the "Sort class elements" option to be enabled in order to take effect!

##### 2.6.6.3.2. Descriptions

Lets you define the description texts for the individual code sections.

Select a row in the list and press the Change... button to invoke a dialog that lets you specify the text for a specific section. The dialog may be invoked directly by double-clicking on the list.

Figure 2.57. Configure Section Description Text

If you want to disable the insertion for specific sections, you can achieve this means be removing the description text(s) in question.

Please note that the "Ordinary methods" text is only meaningful when custom grouping is enabled, and specifies the section name for those methods that have no custom grouping info associated (see the section called "Custom Sort Order").

##### 2.6.6.3.3. Style

Lets you control the style of separator comments.

###### Fill character

Lets you define the fill character that should be used in comments.

Example 2.717. Fill character styles

    //~ Methods

    //~ Methods ............................................................

    //~ Methods ------------------------------------------------------------

    //~ Methods ============================================================

    //~ Methods ************************************************************

    //~ Methods ////////////////////////////////////////////////////////////

###### Configure...

Press the Configure... button to adjust the templates that will be used for separator comments. The templates may contain one or several single-line or multi-line comments.

You can configure two different templates: one for the comments between the different declaration sections, and one for comments between method declarations.

Example 2.718. Default separator template

    //~ ${description} ${fill.character}*

As you can see in the example above, certain variables may be used that are substituted during formatting to include the code section description or stretch the comment to completely fill a line.

Table 2.3. Separator template variables

Variable | Description
--- | ---
${description} | Lets you include the description text of the current code section (Refer to Section 2.6.6.3.2, "Separator Comment Descriptions" for information on how to adjust the descriptions).
${fill.character} | Lets you include the fill character as defined by the corresponding combo box. Please note that you have to place an asterix (`*`) after the variable if you want to have a comment line stretched to the full line length.

Please note that Jalopy needs a way to differ between user comments and separator comments, because separator comments must be removed on each run in order to ensure correct locations and behavior.

Jalopy recognizes all single-line comments starting with `//~` as separator comments. If you would rather use a multi-line comment instead or don't like the default identifier, you need to make sure that the comment gets removed. This means can be achieved by adding a unique identifier into the template and configure a custom removal pattern for it (see Section 2.6.8.3, "Comment Removal").

Example 2.719. Multi-line comment separator template

    /**${fill.character}*
     *    ~#~       ${description}:
     *${fill.character}*/

In the example above, `~#~` would be configured as the removal pattern.

Since 1.4

###### Line length

Lets you define the maximal line length for separator comments. The specified fill character might be used to increase the length of a separator comment to span exactly until the specified line length.

Since 1.2.1