Package sting

Annotation Interface Factory

@Documented
@Retention(RUNTIME)
@Target(TYPE)
@StingProvider("[FlatEnclosingName]Sting_[SimpleName]")
public @interface Factory

Annotates an interface for which a dependency-injected factory implementation is to be generated. This annotation is a top-level Sting processor entrypoint. The generated implementation is itself a Sting-managed component and publishes the factory interface via the Typed annotation.

Generated Classname

The generated factory implementation uses the standard Sting naming convention and has the name of the annotated type prepended with Sting_. For example, the top-level type mybiz.MyWidgetFactory will produce the implementation mybiz.Sting_MyWidgetFactory. Nested types are also supported but their names have the $ sign replaced with a _. i.e. The nested class named mybiz.MyOuterClass.MyWidgetFactory will generate an implementation named mybiz.MyOuterClass_Sting_MyWidgetFactory

Factory Methods

Abstract instance methods defined on the factory interface are treated as candidate factory methods. Each candidate method identifies a component type to create and the subset of constructor arguments that are supplied by the caller at runtime. The factory interface may also declare default methods and these are inherited by the generated implementation.

Candidate factory methods must:

• return a concrete class type,
• not declare type parameters,
• not declare thrown exceptions, and
• have parameters whose names and types exactly match constructor parameters on the created type.

The created type must have exactly one constructor accessible from the package containing the factory interface. Constructor parameters omitted from the factory method are treated as Sting-managed dependencies and are injected into the generated factory implementation. This makes it possible to combine services managed by Sting with runtime values supplied by application code.

Injector Integration

The Factory annotation is itself annotated with StingProvider, allowing the factory interface to be included in an Injector.includes() or Fragment.includes() list as a provider-backed type. The generated factory implementation is annotated as an Injectable and Typed component so other Sting-managed components can depend upon the factory interface.

A single factory interface may define multiple factory methods that create different component types.

Example:

 class MyWidget {
   MyWidget( @Nonnull BackendService backendService, int size ) {
   }
 }

 @Factory
 interface MyWidgetFactory {
   @Nonnull MyWidget create( int size );
 }

 @Injector( includes = MyWidgetFactory.class )
 interface MyInjector {
   MyWidgetFactory widgetFactory();
 }
 

In the example above, Sting generates a factory implementation that injects the BackendService dependency and accepts the size parameter from the caller when create(int) is invoked.