Instance Factory Methods

What constructors cannot do

A constructor has to be named after its class. That is fine until you need two ways of building the same thing:

class Angle {
    private final double radians;

    Angle(double radians) { this.radians = radians; }
    Angle(double degrees) { ... }      // will not compile
}

Both take a double, so they have the same signature. Java cannot distinguish them, and no amount of overloading helps.

A factory method solves it by using a name instead:

class Angle {
    private final double radians;

    private Angle(double radians) {          // private: not called directly
        this.radians = radians;
    }

    static Angle ofRadians(double radians) {
        return new Angle(radians);
    }

    static Angle ofDegrees(double degrees) {
        return new Angle(Math.toRadians(degrees));
    }
}

Now the call says what it means:

Angle a = Angle.ofDegrees(90);
Angle b = Angle.ofRadians(Math.PI / 2);

Compare that with new Angle(90), where a reader has to check the constructor to learn which unit is expected. Unit confusion is a real source of robot bugs, and naming the method removes the ambiguity.

Static factory versus instance factory

Both are called factory methods, and the difference is what they belong to.

A static factory belongs to the class being created, as above. Angle.ofDegrees(90).

An instance factory method belongs to some other object, and that object’s state influences what gets built:

class MotorFactory {
    private final boolean inverted;
    private final double maxOutput;

    MotorFactory(boolean inverted, double maxOutput) {
        this.inverted = inverted;
        this.maxOutput = maxOutput;
    }

    Motor create(int port) {
        Motor m = new Motor(port);
        m.setInverted(inverted);
        m.setMaxOutput(maxOutput);
        return m;
    }
}

MotorFactory driveMotors = new MotorFactory(true, 0.8);

Motor left  = driveMotors.create(1);
Motor right = driveMotors.create(2);

The shared configuration lives in the factory, so you set it once rather than repeating it at every creation site. Add a third motor later and it is automatically configured the same way.

This is the form that pairs with dependency injection — you pass a factory to code that needs to create things without deciding how they are configured.

Returning a subtype

The most powerful consequence: a factory can return something more specific than it promises.

abstract class Drivetrain {
    abstract void drive(double speed, double rotation);
}

class TankDrive extends Drivetrain { ... }
class SwerveDrive extends Drivetrain { ... }

class DrivetrainFactory {
    static Drivetrain forRobot(String config) {
        if (config.equals("swerve")) {
            return new SwerveDrive();
        }
        return new TankDrive();
    }
}

Callers get a Drivetrain and never learn which kind:

Drivetrain drive = DrivetrainFactory.forRobot(config);
drive.drive(0.5, 0.0);            // whichever implementation, same call

Runtime polymorphism does the dispatch. The decision about which class to build is made in exactly one place, and every user of Drivetrain is unaffected by it.

Other things factories can do

Validate before constructing. A constructor that throws leaves callers with an awkward failure; a factory can return an Optional or a sensible fallback.

static Optional<Angle> parse(String text) {
    try {
        return Optional.of(ofDegrees(Double.parseDouble(text)));
    } catch (NumberFormatException e) {
        return Optional.empty();
    }
}

Reuse instances. A constructor must produce a new object every time. A factory may hand back a cached one:

class Angle {
    static final Angle ZERO = new Angle(0);

    static Angle ofRadians(double radians) {
        if (radians == 0) return ZERO;         // no new object
        return new Angle(radians);
    }
}

This is why Integer.valueOf(5) is preferred over new Integer(5) — the factory caches small values, and the constructor cannot.

Hide generic clutter.

// the standard library does exactly this
List<String> names = List.of("a", "b", "c");
Map<String, Integer> ports = Map.of("intake", 3);

Constructor or factory

Naming conventions

The standard library is consistent, and following it makes your code predictable:

Next

Related