Over a million developers have joined DZone.

Java Hint Parameters for Immutable Class Constructors

· DevOps Zone

Discover how to optimize your DevOps workflows with our cloud-based automated testing infrastructure, brought to you in partnership with Sauce Labs

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.

Download “The DevOps Journey - From Waterfall to Continuous Delivery” to learn learn about the importance of integrating automated testing into the DevOps workflow, brought to you in partnership with Sauce Labs.


The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}