title: Dagger2 Custom Scopes : How do custom-scopes (@ActivityScope) actually work?
body: <p>I am reading the source code for <a href="https://github.com/joesteele/dagger2-component-scopes-test">Dagger2 Component Scopes Test</a> on GitHub, and I've seen a "custom scope" defined for activities called <code>@ActivityScope</code>, but I've seen it in other projects including the 4-module <a href="https://github.com/android10/Android-CleanArchitecture">CleanArchitecture</a> that has its <code>@PerActivity</code> scope.</p>
  
  <p>But literally, the code for the <code>@ActivityScope</code> annotation is the following:</p>
  
  <pre><code>import java.lang.annotation.Retention;
  import java.lang.annotation.RetentionPolicy;
  
  import javax.inject.Scope;
  
  /**
   * Created by joesteele on 2/15/15.
   */
  @Scope
  @Retention(RetentionPolicy.RUNTIME)
  public @interface ActivityScope {
  }
  </code></pre>
  
  <p>And it is "magically" usable in Modules:</p>
  
  <pre><code>@Module
  public class ActivityModule {
    @Provides @ActivityScope Picasso providePicasso(ComponentTest app, OkHttpClient client) {
      return new Picasso.Builder(app)
          .downloader(new OkHttpDownloader(client))
          .listener(new Picasso.Listener() {
            @Override public void onImageLoadFailed(Picasso picasso, Uri uri, Exception e) {
              Log.e("Picasso", "Failed to load image: " + uri.toString(), e);
            }
          })
          .build();
    }
  }
  </code></pre>
  
  <p>Or the <em>CleanArchitecture</em> example:</p>
  
  <pre><code>@Scope
  @Retention(RUNTIME)
  public @interface PerActivity {}
  
  @PerActivity
  @Component(dependencies = ApplicationComponent.class, modules = ActivityModule.class)
  public interface ActivityComponent {
    //Exposed to sub-graphs.
    Activity activity();
  }
  
  @Module
  public class ActivityModule {
    private final Activity activity;
  
    public ActivityModule(Activity activity) {
      this.activity = activity;
    }
  
    /**
    * Expose the activity to dependents in the graph.
    */
    @Provides @PerActivity Activity activity() {
      return this.activity;
    }
  }
  </code></pre>
  
  <p>I can clearly see that this has to do with JSR-330 custom scopes, but I <strong>really</strong> don't understand what exactly is happening here to make it so that this code enables the given module and/or what is provided by a given module to depend on the actual <code>Activity</code> lifecycle, and for there to exist only a single instance but only if that given activity is active.</p>
  
  <p>The docs say this:</p>
  
  <pre><code>Scope
  
  Dagger 1 only supported a single scope: @Singleton. 
  Dagger 2 allows users to any well-formed scope annotation. 
  The Component docs describe the details of 
      how to properly apply scope to a component.
  </code></pre>
  
  <p>It says to look at the <a href="http://google.github.io/api/latest/dagger/Component.html">Component docs page</a>, but that gives me 404. I also saw <a href="https://github.com/google/dagger/issues/107#issuecomment-71524636">this</a>, but...</p>
  
  <p>May I ask for some help in clarifying why specifying this custom scope magically makes <code>Activity-level scopes</code> work without an issue?</p>
  
  <p>(The answer is, a subscope can receive dependencies from its superscope, and a subscope exists as long as the component does. And that you need to specify the scopes on your modules, and you need to specify your component dependencies to subscope <strong>one</strong> superscope.)</p>