/*
 * Copyright 2017-2020 original 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
 *
 * https://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 io.micronaut.context;

import io.micronaut.context.annotation.ConfigurationReader;
import io.micronaut.context.env.PropertySource;
import io.micronaut.core.util.ArgumentUtils;

import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;

import javax.inject.Singleton;
import java.lang.annotation.Annotation;
import java.util.Map;

An interface for building an application context.
Author:
graemerocher
Since:
1.0/**
 * An interface for building an application context.
 *
 * @author graemerocher
 * @since 1.0
 */
public interface ApplicationContextBuilder {

    
Whether to eager initialize ConfigurationProperties beans. 
Params:
eagerInitConfiguration – True if configuration properties should be eagerly initialized
Returns:
The context builder
Since:
2.0/**
     * Whether to eager initialize {@link io.micronaut.context.annotation.ConfigurationProperties} beans.
     * @param eagerInitConfiguration True if configuration properties should be eagerly initialized
     * @return The context builder
     * @since 2.0
     */
    default @NonNull ApplicationContextBuilder eagerInitConfiguration(boolean eagerInitConfiguration) {
        if (eagerInitConfiguration) {
            return eagerInitAnnotated(ConfigurationReader.class);
        }
        return this;
    }

    
Whether to eager initialize singleton beans.
Params:
eagerInitSingletons – True if singletons should be eagerly initialized
Returns:
The context builder
Since:
2.0/**
     * Whether to eager initialize singleton beans.
     * @param eagerInitSingletons True if singletons should be eagerly initialized
     * @return The context builder
     * @since 2.0
     */
    default @NonNull ApplicationContextBuilder eagerInitSingletons(boolean eagerInitSingletons) {
        if (eagerInitSingletons) {
            return eagerInitAnnotated(Singleton.class);
        }
        return this;
    }

    
Specifies to eager init the given annotated types.
Params:
annotations – The annotation stereotypes
Returns:
The context builder
Since:
2.0/**
     * Specifies to eager init the given annotated types.
     *
     * @param annotations The annotation stereotypes
     * @return The context builder
     * @since 2.0
     */
    @NonNull ApplicationContextBuilder eagerInitAnnotated(Class<? extends Annotation>... annotations);

    
Override default config locations.
Params:
configLocations – The config locations
Returns:
This environment
Since:
2.0/**
     * Override default config locations.
     *
     * @param configLocations The config locations
     * @return This environment
     * @since 2.0
     */
    @NonNull ApplicationContextBuilder overrideConfigLocations(String... configLocations);

    
Additional singletons to register prior to startup.
Params:
beans – The beans
Returns:
This builder/**
     * Additional singletons to register prior to startup.
     *
     * @param beans The beans
     * @return This builder
     */
    @NonNull ApplicationContextBuilder singletons(@Nullable Object... beans);

    
Whether to deduce environments.
Params:
deduceEnvironment – The boolean
Returns:
This builder/**
     * Whether to deduce environments.
     *
     * @param deduceEnvironment The boolean
     * @return This builder
     */
    @NonNull ApplicationContextBuilder deduceEnvironment(@Nullable Boolean deduceEnvironment);

    
The environments to use.
Params:
environments – The environments
Returns:
This builder/**
     * The environments to use.
     *
     * @param environments The environments
     * @return This builder
     */
    @NonNull ApplicationContextBuilder environments(@Nullable String... environments);

    
The environments to use if no other environments are specified.
Params:
environments – The environments
Returns:
This builder/**
     * The environments to use if no other environments are specified.
     *
     * @param environments The environments
     * @return This builder
     */
    @NonNull ApplicationContextBuilder defaultEnvironments(@Nullable String... environments);

    
The packages to include for package scanning.
Params:
packages – The packages
Returns:
This builder/**
     * The packages to include for package scanning.
     *
     * @param packages The packages
     * @return This builder
     */
    @NonNull ApplicationContextBuilder packages(@Nullable String... packages);

    
Properties to override from the environment.
Params:
properties – The properties
Returns:
This builder/**
     * Properties to override from the environment.
     *
     * @param properties The properties
     * @return This builder
     */
    @NonNull ApplicationContextBuilder properties(@Nullable Map<String, Object> properties);

    
Additional property sources.
Params:
propertySources – The property sources to include
Returns:
This builder/**
     * Additional property sources.
     *
     * @param propertySources The property sources to include
     * @return This builder
     */
    @NonNull ApplicationContextBuilder propertySources(@Nullable PropertySource... propertySources);

    
Set whether environment variables should contribute to configuration.
Params:
environmentPropertySource – The boolean
Returns:
This builder/**
     * Set whether environment variables should contribute to configuration.
     *
     * @param environmentPropertySource The boolean
     * @return This builder
     */
    @NonNull ApplicationContextBuilder environmentPropertySource(boolean environmentPropertySource);

    
Which environment variables should contribute to configuration.
Params:
environmentVariables – The environment variables
Returns:
This builder/**
     * Which environment variables should contribute to configuration.
     *
     * @param environmentVariables The environment variables
     * @return This builder
     */
    @NonNull ApplicationContextBuilder environmentVariableIncludes(@Nullable String... environmentVariables);

    
Which environment variables should not contribute to configuration.
Params:
environmentVariables – The environment variables
Returns:
This builder/**
     * Which environment variables should not contribute to configuration.
     *
     * @param environmentVariables The environment variables
     * @return This builder
     */
    @NonNull ApplicationContextBuilder environmentVariableExcludes(@Nullable String... environmentVariables);

    
The main class used by this application.
Params:
mainClass – The main class
Returns:
This builder/**
     * The main class used by this application.
     *
     * @param mainClass The main class
     * @return This builder
     */
    @NonNull ApplicationContextBuilder mainClass(@Nullable Class mainClass);

    
The class loader to be used.
Params:
classLoader – The classloader
Returns:
This builder/**
     * The class loader to be used.
     *
     * @param classLoader The classloader
     * @return This builder
     */
    @NonNull ApplicationContextBuilder classLoader(@Nullable ClassLoader classLoader);

    
Builds the ApplicationContext, but does not start it. 
Returns:
The built, but not running ApplicationContext/**
     * Builds the {@link ApplicationContext}, but does not start it.
     *
     * @return The built, but not running {@link ApplicationContext}
     */
    @NonNull ApplicationContext build();

    
Allow customizing the configurations that will be loaded.
Params:
configurations – The configurations to include
Returns:
This application/**
     * Allow customizing the configurations that will be loaded.
     *
     * @param configurations The configurations to include
     * @return This application
     */
    @NonNull ApplicationContextBuilder include(@Nullable String... configurations);

    
Allow customizing the configurations that will be loaded.
Params:
configurations – The configurations to exclude
Returns:
This application/**
     * Allow customizing the configurations that will be loaded.
     *
     * @param configurations The configurations to exclude
     * @return This application
     */
    @NonNull ApplicationContextBuilder exclude(@Nullable String... configurations);

    
Set the command line arguments.
Params:
args – The arguments
Returns:
This application/**
     * Set the command line arguments.
     *
     * @param args The arguments
     * @return This application
     */
    default  @NonNull ApplicationContextBuilder args(@Nullable String... args) {
        return this;
    }

    
Starts the ApplicationContext. 
Returns:
The running ApplicationContext/**
     * Starts the {@link ApplicationContext}.
     *
     * @return The running {@link ApplicationContext}
     */
    default @NonNull ApplicationContext start() {
        return build().start();
    }

    
Run the ApplicationContext with the given type. Returning an instance of the type. 
Params:
type –         The type of the bean to run
Type parameters:
<T> –  The type, a subclass of AutoCloseable. The close method of the implementation should shutdown the context.
Returns:
The running bean/**
     * Run the {@link ApplicationContext} with the given type. Returning an instance of the type.
     *
     * @param type         The type of the bean to run
     * @param <T>          The type, a subclass of {@link AutoCloseable}. The close method of the implementation should shutdown the context.
     * @return The running bean
     */
    default @NonNull <T extends AutoCloseable> T run(@NonNull Class<T> type) {
        ArgumentUtils.requireNonNull("type", type);
        ApplicationContext applicationContext = start();
        T bean = applicationContext.getBean(type);
        if (bean instanceof LifeCycle) {
            LifeCycle lifeCycle = (LifeCycle) bean;
            if (!lifeCycle.isRunning()) {
                lifeCycle.start();
            }
        }
        return bean;
    }
}