Over a million developers have joined DZone.

Java Hint Parameters for Immutable Class Constructors

DZone's Guide to

Java Hint Parameters for Immutable Class Constructors

· DevOps Zone ·
Free Resource

DevOps involves integrating development, testing, deployment and release cycles into a collaborative process. Learn more about the 4 steps to an effective DevSecOps infrastructure.

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.

Read the 4-part DevOps testing eBook to learn how to detect problems earlier in your DevOps testing processes.


Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}