3.7 Bean Factories

In many cases, you may want to make available as a bean a class that is not part of your codebase such as those provided by third-party libraries. In this case, you cannot annotate the already compiled class. Instead, you should implement a @Factory.

A factory is a class annotated with the Factory annotation that provides 1 or more methods annotated with a bean scope annotation. Which annotation you use depends on what scope you want the bean to be in. See the section on bean scopes for more information.

The return types of methods annotated with a bean scope annotation are the bean types. This is best illustrated by an example:

  1. @Singleton
  2. class CrankShaft {
  3. }
  4. class V8Engine implements Engine {
  5. private final int cylinders = 8;
  6. private final CrankShaft crankShaft;
  7. public V8Engine(CrankShaft crankShaft) {
  8. this.crankShaft = crankShaft;
  9. }
  10. public String start() {
  11. return "Starting V8";
  12. }
  13. }
  14. @Factory
  15. class EngineFactory {
  16. @Singleton
  17. Engine v8Engine(CrankShaft crankShaft) {
  18. return new V8Engine(crankShaft);
  19. }
  20. }
  1. @Singleton
  2. class CrankShaft {
  3. }
  4. class V8Engine implements Engine {
  5. final int cylinders = 8
  6. final CrankShaft crankShaft
  7. V8Engine(CrankShaft crankShaft) {
  8. this.crankShaft = crankShaft
  9. }
  10. String start() {
  11. "Starting V8"
  12. }
  13. }
  14. @Factory
  15. class EngineFactory {
  16. @Singleton
  17. Engine v8Engine(CrankShaft crankShaft) {
  18. new V8Engine(crankShaft)
  19. }
  20. }
  1. @Singleton
  2. internal class CrankShaft
  3. internal class V8Engine(private val crankShaft: CrankShaft) : Engine {
  4. private val cylinders = 8
  5. override fun start(): String {
  6. return "Starting V8"
  7. }
  8. }
  9. @Factory
  10. internal class EngineFactory {
  11. @Singleton
  12. fun v8Engine(crankShaft: CrankShaft): Engine {
  13. return V8Engine(crankShaft)
  14. }
  15. }

In this case, the V8Engine is built by the EngineFactory class’ v8Engine method. Note that you can inject parameters into the method and these parameters will be resolved as beans. The resulting V8Engine bean will be a singleton.

A factory can have multiple methods annotated with bean scope annotations, each one returning a distinct bean type.

If you take this approach, then you should not invoke other bean methods internally within the class. Instead, inject the types via parameters.
To allow the resulting bean to participate in the application context shutdown process, annotate the method with @Bean and set the preDestroy argument to the name of the method that should be called to close the bean.

Programmatically Disabling Beans

Factory methods can return throw DisabledBeanException to allow for beans to be disabled conditionally. The use of @Requires should always be the preferred method to conditionally create beans and throwing an exception a factory method should only be done if using @Requires is not possible.

For example:

  1. public interface Engine {
  2. Integer getCylinders();
  3. }
  4. @EachProperty("engines")
  5. public class EngineConfiguration implements Toggleable {
  6. private boolean enabled = true;
  7. private Integer cylinders;
  8. @NotNull
  9. public Integer getCylinders() {
  10. return cylinders;
  11. }
  12. public void setCylinders(Integer cylinders) {
  13. this.cylinders = cylinders;
  14. }
  15. @Override
  16. public boolean isEnabled() {
  17. return enabled;
  18. }
  19. public void setEnabled(boolean enabled) {
  20. this.enabled = enabled;
  21. }
  22. }
  23. @Factory
  24. public class EngineFactory {
  25. @EachBean(EngineConfiguration.class)
  26. public Engine buildEngine(EngineConfiguration engineConfiguration) {
  27. if (engineConfiguration.isEnabled()) {
  28. return engineConfiguration::getCylinders;
  29. } else {
  30. throw new DisabledBeanException("Engine configuration disabled");
  31. }
  32. }
  33. }
  1. interface Engine {
  2. Integer getCylinders()
  3. }
  4. @EachProperty("engines")
  5. class EngineConfiguration implements Toggleable {
  6. boolean enabled = true
  7. @NotNull
  8. Integer cylinders
  9. }
  10. @Factory
  11. class EngineFactory {
  12. @EachBean(EngineConfiguration)
  13. Engine buildEngine(EngineConfiguration engineConfiguration) {
  14. if (engineConfiguration.enabled) {
  15. (Engine){ -> engineConfiguration.cylinders }
  16. } else {
  17. throw new DisabledBeanException("Engine configuration disabled")
  18. }
  19. }
  20. }
  1. interface Engine {
  2. fun getCylinders(): Int
  3. }
  4. @EachProperty("engines")
  5. class EngineConfiguration : Toggleable {
  6. val enabled = true
  7. @NotNull
  8. val cylinders: Int? = null
  9. override fun isEnabled(): Boolean {
  10. return enabled
  11. }
  12. }
  13. @Factory
  14. class EngineFactory {
  15. @EachBean(EngineConfiguration::class)
  16. fun buildEngine(engineConfiguration: EngineConfiguration): Engine? {
  17. return if (engineConfiguration.isEnabled) {
  18. object : Engine {
  19. override fun getCylinders(): Int {
  20. return engineConfiguration.cylinders!!
  21. }
  22. }
  23. } else {
  24. throw DisabledBeanException("Engine configuration disabled")
  25. }
  26. }
  27. }

Injection Point

A common use case with factories is to take advantage of annotation metadata from the point at which an object is injected such that behaviour can be modified based on said metadata.

Consider an annotation such as the following:

  1. @Documented
  2. @Retention(RUNTIME)
  3. @Target(ElementType.PARAMETER)
  4. public @interface Cylinders {
  5. int value() default 8;
  6. }
  1. @Documented
  2. @Retention(RUNTIME)
  3. @Target(ElementType.PARAMETER)
  4. @interface Cylinders {
  5. int value() default 8
  6. }
  1. @MustBeDocumented
  2. @Retention(AnnotationRetention.RUNTIME)
  3. @Target(AnnotationTarget.VALUE_PARAMETER)
  4. annotation class Cylinders(val value: Int = 8)

The above annotation could be used to customize the type of engine we want to inject into a vehicle at the point at which the injection point is defined:

  1. @Singleton
  2. class Vehicle {
  3. private final Engine engine;
  4. Vehicle(@Cylinders(6) Engine engine) {
  5. this.engine = engine;
  6. }
  7. String start() {
  8. return engine.start();
  9. }
  10. }
  1. @Singleton
  2. class Vehicle {
  3. private final Engine engine
  4. Vehicle(@Cylinders(6) Engine engine) {
  5. this.engine = engine
  6. }
  7. String start() {
  8. return engine.start()
  9. }
  10. }
  1. @Singleton
  2. internal class Vehicle(@param:Cylinders(6) private val engine: Engine) {
  3. fun start(): String {
  4. return engine.start()
  5. }
  6. }

The above Vehicle class specifies an annotation value of @Cylinders(6) indicating an Engine of six cylinders is needed.

To implement this use case you can define a factory that accepts the InjectionPoint instance which can be used to analyze the annotation values defined:

  1. @Factory
  2. class EngineFactory {
  3. @Prototype
  4. Engine v8Engine(InjectionPoint<?> injectionPoint, CrankShaft crankShaft) { (1)
  5. final int cylinders = injectionPoint
  6. .getAnnotationMetadata()
  7. .intValue(Cylinders.class).orElse(8); (2)
  8. switch (cylinders) { (3)
  9. case 6:
  10. return new V6Engine(crankShaft);
  11. case 8:
  12. return new V8Engine(crankShaft);
  13. default:
  14. throw new IllegalArgumentException("Unsupported number of cylinders specified: " + cylinders);
  15. }
  16. }
  17. }
  1. @Factory
  2. class EngineFactory {
  3. @Prototype
  4. Engine v8Engine(InjectionPoint<?> injectionPoint, CrankShaft crankShaft) { (1)
  5. final int cylinders = injectionPoint
  6. .getAnnotationMetadata()
  7. .intValue(Cylinders.class).orElse(8) (2)
  8. switch (cylinders) { (3)
  9. case 6:
  10. return new V6Engine(crankShaft)
  11. case 8:
  12. return new V8Engine(crankShaft)
  13. default:
  14. throw new IllegalArgumentException("Unsupported number of cylinders specified: $cylinders")
  15. }
  16. }
  17. }
  1. @Factory
  2. internal class EngineFactory {
  3. @Prototype
  4. fun v8Engine(injectionPoint: InjectionPoint<*>, crankShaft: CrankShaft): Engine { (1)
  5. val cylinders = injectionPoint
  6. .annotationMetadata
  7. .intValue(Cylinders::class.java).orElse(8) (2)
  8. return when (cylinders) { (3)
  9. 6 -> V6Engine(crankShaft)
  10. 8 -> V8Engine(crankShaft)
  11. else -> throw IllegalArgumentException("Unsupported number of cylinders specified: $cylinders")
  12. }
  13. }
  14. }
1The factory method defines a parameter of type InjectionPoint.
2The annotation metadata is used to obtain the value of the @Cylinder annotation
3The value is used to construct an engine, throwing an exception if an engine cannot be constructed.
It is important to note that the factory is declared as @Prototype scope so that the method is invoked for each injection point. If the V8Engine and V6Engine types are required to be singletons then the factory should use a map to ensure the objects are only constructed once.