/*
 * Copyright (C) 2020 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.assisted;

import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * Annotates the constuctor of a type that will be created via assisted injection.
 *
 * <p>Note that an assisted injection type cannot be scoped. In addition, assisted injection
 * requires the use of a factory annotated with {@link AssistedFactory} (see the example below).
 *
 * <p>Example usage:
 *
 * <p>Suppose we have a type, {@code DataService}, that has two dependencies: {@code DataFetcher}
 * and {@code Config}. When creating {@code DataService}, we would like to pass in an instance of
 * {@code Config} manually rather than having Dagger create it for us. This can be done using
 * assisted injection.
 *
 * <p>To start, we annotate the {@code DataService} constructor with {@link AssistedInject} and we
 * annotate the {@code Config} parameter with {@link Assisted}, as shown below:
 *
 * <pre><code>
 *   final class DataService {
 *     private final DataFetcher dataFetcher;
 *     private final Config config;
 *
 *     {@literal @}AssistedInject
 *     DataService(DataFetcher dataFetcher, {@literal @}Assisted Config config) {
 *       this.dataFetcher = dataFetcher;
 *       this.config = config;
 *     }
 *   }
 * </code></pre>
 *
 * <p>Next, we define a factory for the assisted type, {@code DataService}, and annotate it with
 * {@link AssistedFactory}. The factory must contain a single abstract, non-default method which
 * takes in all of the assisted parameters (in order) and returns the assisted type.
 *
 * <pre><code>
 *   {@literal @}AssistedFactory
 *   interface DataServiceFactory {
 *     DataService create(Config config);
 *   }
 * </code></pre>
 *
 * <p>Dagger will generate an implementation of the factory and bind it to the factory type. The
 * factory can then be used to create an instance of the assisted type:
 *
 * <pre><code>
 *   class MyApplication {
 *     {@literal @}Inject DataServiceFactory dataServiceFactory;
 *
 *     dataService = dataServiceFactory.create(new Config(...));
 *   }
 * </code></pre>
 */
@Documented
@Retention(RUNTIME)
@Target(CONSTRUCTOR)
public @interface AssistedInject {}