DevOps Zone is brought to you in partnership with:

Oliver has posted 1 posts at DZone. You can read more from them at their website. View Full User Profile

Java Hint Parameters for Immutable Class Constructors

04.02.2013
| 2375 views |
  • submit to reddit

Constructing an immutable class in Java is simple if the number of parameters is small. However, when the parameters increase in number, it can be hard to tell the meaning of the arguments passed to the constructor. Named parameters, as exists in other languages would help, but don't exist in Java. The builder methodology is a solution, but requires a shadow class or non final instance fields.

Hint Parameters provide hints to the caller (or reader) of a constructor, about the names or fluent meaning of the parameters that follow the hint. They may hint at one, two or more parameters at a time. To do this they use an argument naming syntax which separates sections of the hint with a "_" character.

Hints should be used in a strict order which stand out when entering or reading the constructor call. To ensure this, the first section starts with the hint number and then indicates a contract of whether the parameters are required, defaulted, or optional using the letters "r", "d" and "o".

The implementation uses static java enums with lowercase (or CamelCase) values to ensure readability. A simple example:

package myth;
import static com.google.common.base.Preconditions.checkNotNull;
 
public final class Dragon {
    private final Integer height, width, rating;
    private final String name;
     
    public static enum Hint {_1rr_height_width, _2do_rating_name} 
    public Dragon(Hint h1, Integer height, Integer width, 
                  Hint h2, Integer rating, String name) {
        this.height = checkNotNull(height, "Height is required");
        this.width = checkNotNull(width, "Width is required");
        this.rating = (rating == null) ? 1 : rating;
        this.name = name;
    }
    // other methods
}

Another class calling the hinted constructor:

package myth;
import static myth.Dragon.Hint.*;
public class DragonRun {
    public static void main(String [] args) {
        
        Dragon fierceDragon = new Dragon(
                _1rr_height_width, 1, 2,
                _2do_rating_name, null, "Fierce Dragon"
        );
        
    }  
}

The null value is used as a placeholder. When the contract indicates a parameter has a default via "d", the default value will be used in place of the null. When the parameter is optional via "o", null will be used.

If all parameters of the constructor are required, the "r" indicators can be dropped.

Notes:

Using a static java enum type to implement the Hint Parameters has the advantage of simplicity and code clarity. It has a disadvantage in that the parameters could be used out of order.  The numbering convention makes this unlikely, but if necessary, the order could be checked at run time. Another possible implementation would be to use separate static hint classes which would ensure type safety at the expense of simplicity.

Hint Parameters could also be used in static or instance methods calls as well as mutable class constructors.

Published at DZone with permission of its author, Oliver Staats.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Jarek Krochmalski replied on Tue, 2013/04/02 - 9:48am

m

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.