Package magnet

Annotation Type Instance

  • @Retention(CLASS)
@Target({TYPE,METHOD})
public @interface Instance
    Magnet instantiates classes marked with this annotation automatically. Annotated classes must have a single, none private constructor. Constructor is allowed to have parameters which are dependencies for this instance. Magnet checks constructor parameters and tries to resolve corresponding dependencies by looking into accessible scopes. If no suitable instances were found in scopes, Magnet searches for Instance-annotated classes and tried to instantiate them. If constructor's dependencies cannot be fulfilled, Magnet will fail at runtime with corresponding error message.

    In the example below we declare two dependent types and instantiate them in scope. 

         @Instance(type=TypeA.class)
     class TypeA {
         TypeA() {}
     }

     @Instance(type=TypeB.class)
     class TypeB {
         final TypeA typeA;
         TypeB(@NonNull TypeA dependency) {
             typeA = dependency;
         }
     }

     ...

     // get instance of typeB
     TypeB typeB = scope.getSingle(TypeB.class);

     // typeA has been provided by Magnet
     typeB.typeA != null

    Nullability. Magnet is capable of detecting whether dependency can or cannot be null. If a constructor's parameter is annotated as nullable and Magnet cannot provide instance of parameter's type, then null is provided instead.

    Classification. Same interface can be implemented by many classes. Classifier is used to differentiate between those implementations. See Classifier for more detail.

    Scoping. Magnet can bind created instances into scope for reuse. Instance can specify whether and how its instances should be bound into the scope. See Scoping for more detail.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.String classifier
      Classifier to use when annotated instance gets registered in scope.
      boolean disabled
      Magnet ignores this annotation when this flag is set to true.
      java.lang.String disposer
      Name of optional disposer method to be called, when whole scope gets disposed.
      java.lang.Class<? extends Factory> factory
      Custom factory to be used for creating instance instead of the generated one.
      java.lang.String limitedTo
      Limit tag to be used with Scoping.TOPMOST algorithm.
      Scoping scoping
      Scoping rule to be applied when instance of annotated class gets created.
      java.lang.String selector
      Experimental. Magnet will only create instance of the annotated class if this selector expression is true after evaluation.
      java.lang.Class<?> type
      Type to use when annotated instance gets registered in scope.
      java.lang.Class<?>[] types
      Multiple types to use when annotated instance gets registered in scope.

    • Element Detail

      • type

        java.lang.Class<?> type
        Type to use when annotated instance gets registered in scope. Annotated class must actually implement this type.
        Default:
        void.class

      • types

        java.lang.Class<?>[] types
        Multiple types to use when annotated instance gets registered in scope. Annotated class must actually implement all these types. Properties type() and #types() are exclusively mutual and cannot be used together.
        Default:
        {void.class}

      • classifier

        java.lang.String classifier
        Classifier to use when annotated instance gets registered in scope.
        Default:
        ""

      • scoping

        Scoping scoping
        Scoping rule to be applied when instance of annotated class gets created.
        Default:
        magnet.Scoping.TOPMOST

      • limitedTo

        java.lang.String limitedTo
        Limit tag to be used with Scoping.TOPMOST algorithm. If a limit tag is preset then the instance will be placed at or below the scope having same limit tag applied to it. If multiple scopes have the same limit tag, then the closest scope to the scope where the instance gets requested is used.
        Default:
        ""

      • selector

        java.lang.String selector
        Experimental. Magnet will only create instance of the annotated class if this selector expression is true after evaluation. Magnet currently support single type of expression:

        android.api (comparison operator) (api version)

        For instance, the expression android.api >= 28 will only create annotated instance if Build.VERSION.SDK_INT >= 28. For the other versions null is returned. Make sure to use optional injection to handle this case.

        Default:
        ""

      • factory

        java.lang.Class<? extends Factory> factory
        Custom factory to be used for creating instance instead of the generated one.
        Default:
        magnet.Factory.class

      • disposer

        java.lang.String disposer
        Name of optional disposer method to be called, when whole scope gets disposed.
        Default:
        ""

      • disabled

        boolean disabled
        Magnet ignores this annotation when this flag is set to true.
        Default:
        false