dagger.producers.ProductionComponent Maven / Gradle / Ivy
Show all versions of dagger-producers Show documentation
/*
* Copyright (C) 2014 The Dagger Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package dagger.producers;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import com.google.common.util.concurrent.ListenableFuture;
import dagger.Component;
import dagger.Module;
import dagger.Provides;
import dagger.internal.Beta;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import javax.inject.Inject;
import javax.inject.Qualifier;
/**
* Annotates an interface or abstract class for which a fully-formed, dependency-injected
* implementation is to be generated from a set of {@linkplain #modules modules}. The generated
* class will have the name of the type annotated with {@code @ProductionComponent} prepended with
* {@code Dagger}. For example, {@code @ProductionComponent interface MyComponent {...}} will
* produce an implementation named {@code DaggerMyComponent}.
*
* Each {@link Produces} method that contributes to the component will be called at most once per
* component instance, no matter how many times that binding is used as a dependency. TODO(beder):
* Decide on how scope works for producers.
*
*
Component methods
*
* Every type annotated with {@code @ProductionComponent} must contain at least one abstract
* component method. Component methods must represent {@linkplain Producer production}.
*
*
Production methods have no arguments and return either a {@link ListenableFuture} or {@link
* Producer} of a type that is {@link Inject injected}, {@link Provides provided}, or {@link
* Produces produced}. Each may have a {@link Qualifier} annotation as well. The following are all
* valid production method declarations:
*
*
* {@literal ListenableFuture} getSomeType();
* {@literal Producer>} getSomeTypes();
* {@literal @Response ListenableFuture} getResponse();
*
*
* Exceptions
*
* When a producer throws an exception, the exception will be propagated to its downstream
* producers in the following way: if the downstream producer injects a type {@code T}, then that
* downstream producer will be skipped, and the exception propagated to its downstream producers;
* and if the downstream producer injects a {@code Produced}, then the downstream producer will
* be run with the exception stored in the {@code Produced}.
*
* If a non-execution exception is thrown (e.g., an {@code InterruptedException} or {@code
* CancellationException}), then exception is handled as in {@link
* com.google.common.util.concurrent.Futures#transform}.
*
*
*
Executor
*
* The component must include a binding for {@literal @}{@link Production}
* {@link java.util.concurrent.Executor}; this binding will be called exactly once, and the
* provided executor will be used by the framework to schedule all producer methods (for this
* component, and any {@link ProductionSubcomponent} it may have.
*
* @since 2.0
*/
@Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
@Documented
@Target(TYPE)
@Beta
public @interface ProductionComponent {
/**
* A list of classes annotated with {@link Module} or {@link ProducerModule} whose bindings are
* used to generate the component implementation.
*/
Class[] modules() default {};
/**
* A list of types that are to be used as component dependencies.
*/
Class[] dependencies() default {};
/**
* A builder for a production component.
*
*
This follows all the rules of {@link Component.Builder}, except it must appear in classes
* annotated with {@link ProductionComponent} instead of {@code Component}.
*/
@Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
@Target(TYPE)
@Documented
@interface Builder {}
/**
* A factory for a production component.
*
*
This follows all the rules of {@link Component.Factory}, except it must appear in classes
* annotated with {@link ProductionComponent} instead of {@code Component}.
*
* @since 2.22
*/
@Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
@Target(TYPE)
@Documented
@interface Factory {}
}