1 /*
2  * Copyright (C) 2016 The Dagger Authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package dagger.android;
18 
19 import dagger.BindsInstance;
20 import dagger.internal.Beta;
21 
22 /**
23  * Performs members-injection for a concrete subtype of a <a
24  * href="https://developer.android.com/guide/components/">core Android type</a> (e.g., {@link
25  * android.app.Activity} or {@link android.app.Fragment}).
26  *
27  * <p>Commonly implemented by {@link dagger.Subcomponent}-annotated types whose {@link
28  * dagger.Subcomponent.Factory} extends {@link Factory}.
29  *
30  * @param <T> a concrete subtype of a core Android type
31  * @see AndroidInjection
32  * @see DispatchingAndroidInjector
33  * @see ContributesAndroidInjector
34  */
35 @Beta
36 public interface AndroidInjector<T> {
37 
38   /** Injects the members of {@code instance}. */
inject(T instance)39   void inject(T instance);
40 
41   /**
42    * Creates {@link AndroidInjector}s for a concrete subtype of a core Android type.
43    *
44    * @param <T> the concrete type to be injected
45    */
46   interface Factory<T> {
47     /**
48      * Creates an {@link AndroidInjector} for {@code instance}. This should be the same instance
49      * that will be passed to {@link #inject(Object)}.
50      */
create(@indsInstance T instance)51     AndroidInjector<T> create(@BindsInstance T instance);
52   }
53 
54   /**
55    * An adapter that lets the common {@link dagger.Subcomponent.Builder} pattern implement {@link
56    * Factory}.
57    *
58    * @param <T> the concrete type to be injected
59    * @deprecated Prefer {@link Factory} now that components can have {@link dagger.Component.Factory
60    *     factories} instead of builders
61    */
62   @Deprecated
63   abstract class Builder<T> implements AndroidInjector.Factory<T> {
64     @Override
create(T instance)65     public final AndroidInjector<T> create(T instance) {
66       seedInstance(instance);
67       return build();
68     }
69 
70     /**
71      * Provides {@code instance} to be used in the binding graph of the built {@link
72      * AndroidInjector}. By default, this is used as a {@link BindsInstance} method, but it may be
73      * overridden to provide any modules which need a reference to the activity.
74      *
75      * <p>This should be the same instance that will be passed to {@link #inject(Object)}.
76      */
77     @BindsInstance
seedInstance(T instance)78     public abstract void seedInstance(T instance);
79 
80     /** Returns a newly-constructed {@link AndroidInjector}. */
build()81     public abstract AndroidInjector<T> build();
82   }
83 }
84