Package magnet

Interface Scope

  • public interface Scope
    Scope is a container for objects which are stored there at runtime.

    Binding. Binding is the way of putting objects into the scope. 

     Scope root = Magnet.createScope()
                 .bind(app, Application.class)
                 .bind(String.class, "#FF0000", "red-color");

    Chaining. Scopes can be chained using parent-child relation, or rather a child-parent relation because a child scope (aka subscope) holds a reference to its parent and not the other way around. 

     Scope subscope = root.createSubscope()
                   .bind(activity, Context.class)
                   .bind(String.class, "#F30303", "red-color")
                   .bind(String.class, "#00FF00", "green-color");
    Provisioning. Scope has multiple get-methods for providing objects it stores. Magnet will look through the whole scope's chain up to the root parent scope to provide an object. First found match gets returned. 
     // object overwriting
 String red = root.getSingle(String.class, "red-color"); // "#FF0000" (from root)
 String red = subscope.getSingle(String.class, "red-color"); // "#F30303" (from subscope)

 // scope chaining
 Application app = subscope.getSingle(Application.class); // app (from root)
 Context context = subscope.getSingle(Context.class); // activity (from subscope)
 String green = subscope.getSingle(String.class, "green-color"); // "#00FF00" (from subscope)

 // optional provisioning
 String red = root.getOptional(String.class, "red-color"); "#FF0000" (from root)
 String yellow = subscope.getSingle(String.class, "yellow-color"); // throws IllegalStateException
 String yellow = subscope.getOptional(String.class, "yellow-color"); // null, optional was not found

    Automatic binding (injection). Magnet can instantiate Instance-annotated classes and bind their instances into respective scopes automatically. If instantiated classes have dependencies, Magnet will resolve those dependencies too. In this respect Magnet works as dependency injection library.

    In the example below Magnet will create instance of toaster by taking required dependencies from the scopes. 

     @Instance(type = Toaster.class)
 class Toaster {
     Toaster(
         Application app,
         @Classifier("red-color") String red,
         @Classifier("green-color") String green
     ) { ... }

 Toaster toaster = subscope.getSingle(Toaster.class);
 toaster != null

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void accept​(Visitor visitor, int depth)
      Visits all instances and child scopes of given depth (use Integer.MAX_VALUE for visiting all scopes).
      <T> @NotNull Scope bind​(@NotNull java.lang.Class<T> type, T instance)
      Binds given instance into this scope.
      <T> @NotNull Scope bind​(@NotNull java.lang.Class<T> type, T instance, @NotNull java.lang.String classifier)
      Binds given instance into this scope.
      @NotNull Scope createSubscope()
      Creates a new child scope of this scope.
      void dispose()
      Disposes this and all children scopes.
      <T> @NotNull java.util.List<T> getMany​(@NotNull java.lang.Class<T> type)
      Returns a list of objects or empty list, if no objects were found.
      <T> @NotNull java.util.List<T> getMany​(@NotNull java.lang.Class<T> type, @NotNull java.lang.String classifier)
      Returns a list of objects or empty list, if no objects were found.
      <T> T getOptional​(@NotNull java.lang.Class<T> type)
      Returns an object from the scope or null, if object was not found.
      <T> T getOptional​(@NotNull java.lang.Class<T> type, @NotNull java.lang.String classifier)
      Returns an object from the scope or null, if object was not found.
      <T> T getSingle​(@NotNull java.lang.Class<T> type)
      Returns an object from the scope or throws exception, if object was not found.
      <T> T getSingle​(@NotNull java.lang.Class<T> type, @NotNull java.lang.String classifier)
      Returns an object from the scope or throws exception, if object was not found.
      boolean isDisposed()
      Returns `true` is the scope is disposed, or `false` otherwise.
      @NotNull Scope limit​(java.lang.String... limits)
      Sets given limits to this scope.

    • Method Detail

      • getOptional

        @Nullable
<T> T getOptional​(@NotNull
                  @NotNull java.lang.Class<T> type)
        Returns an object from the scope or null, if object was not found.

      • getOptional

        @Nullable
<T> T getOptional​(@NotNull
                  @NotNull java.lang.Class<T> type,
                  @NotNull
                  @NotNull java.lang.String classifier)
        Returns an object from the scope or null, if object was not found.

      • getSingle

        @NotNull
<T> T getSingle​(@NotNull
                @NotNull java.lang.Class<T> type)
        Returns an object from the scope or throws exception, if object was not found.

      • getSingle

        @NotNull
<T> T getSingle​(@NotNull
                @NotNull java.lang.Class<T> type,
                @NotNull
                @NotNull java.lang.String classifier)
        Returns an object from the scope or throws exception, if object was not found.

      • getMany

        @NotNull
<T> @NotNull java.util.List<T> getMany​(@NotNull
                                       @NotNull java.lang.Class<T> type)
        Returns a list of objects or empty list, if no objects were found.

      • getMany

        @NotNull
<T> @NotNull java.util.List<T> getMany​(@NotNull
                                       @NotNull java.lang.Class<T> type,
                                       @NotNull
                                       @NotNull java.lang.String classifier)
        Returns a list of objects or empty list, if no objects were found.

      • bind

        @NotNull
<T> @NotNull Scope bind​(@NotNull
                        @NotNull java.lang.Class<T> type,
                        @NotNull
                        T instance)
        Binds given instance into this scope.

      • bind

        @NotNull
<T> @NotNull Scope bind​(@NotNull
                        @NotNull java.lang.Class<T> type,
                        @NotNull
                        T instance,
                        @NotNull
                        @NotNull java.lang.String classifier)
        Binds given instance into this scope.

      • limit

        @NotNull
@NotNull Scope limit​(java.lang.String... limits)
        Sets given limits to this scope.

      • createSubscope

        @NotNull
@NotNull Scope createSubscope()
        Creates a new child scope of this scope.

      • dispose

        void dispose()
        Disposes this and all children scopes. Notifies instances with Instance.disposer().

      • isDisposed

        boolean isDisposed()
        Returns `true` is the scope is disposed, or `false` otherwise.

      • accept

        void accept​(Visitor visitor,
            int depth)
        Visits all instances and child scopes of given depth (use Integer.MAX_VALUE for visiting all scopes).