Over a million developers have joined DZone.
Gold Partner

Java Hint Parameters for Immutable Class Constructors

· DevOps Zone

The DevOps Zone is brought to you in partnership with Go Continuous Delivery. Learn the 5 key patterns to setting up a successful deployment pipeline, including designing parallel workflows, running tests in parallel, and more.

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.


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.

The DevOps Zone is brought to you in partnership with Go Continuous Delivery. Discover why "Hardly Anyone Knows Continuous Delivery."


{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}