[Skip to content]

2.8.11. Sorting

Lets you control the code sorting. Code sorting lets you arrange elements in a specific order to ease navigation and improve comprehension.

2.8.11.1. Declarations

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

Figure 2.48. Sorting Declarations settings page

Sorting Declarations settings page

Sort declarations

Enables or disables the sorting of declarations. When disabled, all declarations appear in their original order. Otherwise they are grouped and sorted according to the defined order.

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 with the Up and Down buttons.

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 “Sort Members” check boxes, if you want to have all members of one type sorted as well.

Use the Edit... button to configure the order in which the individual declaration 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 enabled 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, the names will be checked and and the two methods sorted lexicographically.

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.8.11.1.1. Methods

Figure 2.49. Configure Sorting Order of Methods

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. To further refine the way sorting is applied for modifiers, select the “Modifiers” entry and press the Edit... button to define what modifiers should be significant and adjust their order.

Example 2.719. 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';.

Bean Pattern

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

Figure 2.50. Configure Sorting Order of JavaBeans Methods

Configure Sorting Order of JavaBeans Methods

You can control the order in which JavaBeans methods and ordinary methods appear by selecting the entry and press the Edit... 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.720. 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.721. Bean pattern sorting, group similar

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.722. Bean pattern sorting, group similar

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.723. Bean pattern sorting, group similar, 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.51. Configure Regular Expression Sorting

Configure Regular Expression Sorting

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

Example 2.724. 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.52. Add Regular Expression

Add Regular Expression

Enter the regular expression into the Regex text field 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.53. Change Regular Expression

Change Regular Expression

Adjust the regular expression in the Regex text field 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.

Important

Javadoc formatting, see Section 2.8.14.1.1, “Format comments”, 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.725. 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.726. 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. A group name not only defines the sorting order, but is used for separator comments also (Refer to Section 2.8.11.3, “Comments” for more information on this feature).

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).

Since 1.1

Example 2.727. 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.8.11.1.2. Static Methods

In order to separate static methods from non-static methods, enable the corresponding checkbox. When enabled, you can move the item up and down to specify the relative position among the other element sections.

The individual static method declarations are sorted according to the criteria defined for non-static methods.

Since 1.9.4

2.8.11.1.3. Classes, Interfaces, Enums

Class, interface, enum and annotation declarations can be sorted according to access modifier and/or name.

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

Configure Sorting Order of Classes, Interfaces and Enums

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

Example 2.728. Classes/Interfaces

protected abstract class AbstractPage {
    ...
}

In the above example, the modifiers would be “protected abstract” and the name “AbstractPage”.

2.8.11.1.4. Access Modifier

Lets you define what modifiers should be significant when sorting by modifier and in which order the declarations should be sorted. The position of the Modifiers entry in the parent dialog defines when the modifiers are compared 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.55. Configure Sorting Order of Modifiers

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.729. 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.730. 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() {}
}

Require bean property field

By default all methods following the JavaBeans naming conventions are recognized as JavaBeans methods. In order to limit JavaBeans detection to methods that actually contain a corresponding property field, enable this option.

Bean property field detection is somewhat fuzzy as no attempt is made to match method names exactly in order to support field prefixes. Given the method name “getImportanceValue”, Jalopy would match all fields that end with “importanceValue” as a corresponding property field (case is ignored). But a field name “importanceValue_” would not be matched.

Since 1.9

Example 2.731. Method declarations

private boolean importanceValue; // property field

public void setImportanceValue(boolean value) {}
public boolean isImportanceValue() {}
public void setTestValue(String value) {}

When the option is disabled, all methods in the above example would be recognized as JavaBeans methods and handled accordingly. But if the option is enabled, only the first two methods would be treated as JavaBeans methods, because only they contain a matching property field.

This option might affect the sorting of methods when the Bean Pattern criteria is enabled, please refer to Section 2.8.11.1.1, “Bean Pattern”. It also impacts what Javadoc template might be chosen when generating Javadoc comments, see Section 2.8.14.5, “Templates”.

Boolean Getter

Lets you configure the regular expression that is used to determine what method declarations are 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 this restriction. In certain cases it is more reasonable to name methods in a way that better describes their purpose, but still treat them as Boolean Getters, like e.g. canDelete() or shouldDelete().

Important

The prefix must be enclosed with matching parentheses! Always use something like ^(is|should|can)[A-Z]\w+ rather than ^is|should|can[A-Z]\w+

Since 1.1

2.8.11.2. Modifiers

Controls the sorting of declaration modifiers.

Figure 2.56. Sorting Modifiers settings page

Sorting Modifiers settings page

Sort modifiers

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

Sort annotations

Controls whether annotations should be sorted lexicographically.

Since 1.9

Example 2.732. Unsorted annotations

@Remote(Whatever.class)
@Interceptors(Test.class)
@Stateful
class Foo {}

Example 2.733. Sorted annotations

@Interceptors(Test.class)
@Remote(Whatever.class)
@Stateful
class Foo {}

2.8.11.2.1. 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 6.0. The @annotation entry represents annotations.

Example 2.734. Marker annotation placed before public modifier

@Preliminary public class TimeTravel {
    ...
}

Example 2.735. 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.736. 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.737. Single-member annotation

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

2.8.11.3. Comments

Lets you control the behavior of the separator comments. When the sorting of declarations 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.738. Separator comment

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

Figure 2.57. Comments Separator settings page

Comments Separator settings page

2.8.11.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.8.11.3.2, “Separator Comment Descriptions” and Section 2.8.11.3.3, “Separator Comment Style”.

Example 2.739. 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 {
      ...
    }
}

Important

The option requires the “Sort declarations” 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.740. 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() {
            ...
        }
    }
}

Important

The option requires the “Sort declarations” 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.741. 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() {
    ...
}

Important

The option requires the “Sort declarations” 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

Important

“Sort declarations” must be enabled in order to take effect

Example 2.742. 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() {
            ...
        }
    }
}

2.8.11.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.58. Configure Section Description Text

Configure Section Description Text

If you want to disable the insertion for specific sections, you can achieve this means by removing the corresponding description text. Please note that the “Ordinary methods” text is only used when custom grouping is enabled, and specifies the section name for those methods that have no custom grouping info associated (see Section 2.8.11.1.1, “Custom Sort Order”).

2.8.11.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.743. Fill character styles

//~ Methods

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

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

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

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

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

Edit...

Press the Edit... 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.744. 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.6. Separator template variables

VariableDescription
${description} Lets you include the description text of the current code section (Refer to Section 2.8.11.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 comments get 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.8.13.3, “Comment Removal”).

Example 2.745. 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