/*
 * Copyright 2002-2020 the original author or 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 org.springframework.context;

import java.io.Closeable;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
import org.springframework.core.env.ConfigurableEnvironment;
import org.springframework.core.env.Environment;
import org.springframework.core.io.ProtocolResolver;

/**
 * SPI interface to be implemented by most if not all application contexts.
 * Provides facilities to configure an application context in addition
 * to the application context client methods in the
 * {@link org.springframework.context.ApplicationContext} interface.
 *
 * <p>Configuration and lifecycle methods are encapsulated here to avoid
 * making them obvious to ApplicationContext client code. The present
 * methods should only be used by startup and shutdown code.
 *
 * @author Juergen Hoeller
 * @author Chris Beams
 * @since 03.11.2003
 */
public interface ConfigurableApplicationContext extends ApplicationContext, Lifecycle, Closeable {

        /**
         * Any number of these characters are considered delimiters between
         * multiple context config paths in a single String value.
         * @see org.springframework.context.support.AbstractXmlApplicationContext#setConfigLocation
         * @see org.springframework.web.context.ContextLoader#CONFIG_LOCATION_PARAM
         * @see org.springframework.web.servlet.FrameworkServlet#setContextConfigLocation
         */
        String CONFIG_LOCATION_DELIMITERS = ",; \t\n";

        /**
         * Name of the ConversionService bean in the factory.
         * If none is supplied, default conversion rules apply.
         * @since 3.0
         * @see org.springframework.core.convert.ConversionService
         */
        String CONVERSION_SERVICE_BEAN_NAME = "conversionService";

        /**
         * Name of the LoadTimeWeaver bean in the factory. If such a bean is supplied,
         * the context will use a temporary ClassLoader for type matching, in order
         * to allow the LoadTimeWeaver to process all actual bean classes.
         * @since 2.5
         * @see org.springframework.instrument.classloading.LoadTimeWeaver
         */
        String LOAD_TIME_WEAVER_BEAN_NAME = "loadTimeWeaver";

        /**
         * Name of the {@link Environment} bean in the factory.
         * @since 3.1
         */
        String ENVIRONMENT_BEAN_NAME = "environment";

        /**
         * Name of the System properties bean in the factory.
         * @see java.lang.System#getProperties()
         */
        String SYSTEM_PROPERTIES_BEAN_NAME = "systemProperties";

        /**
         * Name of the System environment bean in the factory.
         * @see java.lang.System#getenv()
         */
        String SYSTEM_ENVIRONMENT_BEAN_NAME = "systemEnvironment";


        /**
         * Set the unique id of this application context.
         * @since 3.0
         */
        void setId(String id);

        /**
         * Set the parent of this application context.
         * <p>Note that the parent shouldn't be changed: It should only be set outside
         * a constructor if it isn't available when an object of this class is created,
         * for example in case of WebApplicationContext setup.
         * @param parent the parent context
         * @see org.springframework.web.context.ConfigurableWebApplicationContext
         */
        void setParent(ApplicationContext parent);

        /**
         * Set the {@code Environment} for this application context.
         * @param environment the new environment
         * @since 3.1
         */
        void setEnvironment(ConfigurableEnvironment environment);

        /**
         * Return the {@code Environment} for this application context in configurable
         * form, allowing for further customization.
         * @since 3.1
         */
        @Override
        ConfigurableEnvironment getEnvironment();

        /**
         * Add a new BeanFactoryPostProcessor that will get applied to the internal
         * bean factory of this application context on refresh, before any of the
         * bean definitions get evaluated. To be invoked during context configuration.
         * @param postProcessor the factory processor to register
         */
        void addBeanFactoryPostProcessor(BeanFactoryPostProcessor postProcessor);

        /**
         * Add a new ApplicationListener that will be notified on context events
         * such as context refresh and context shutdown.
         * <p>Note that any ApplicationListener registered here will be applied
         * on refresh if the context is not active yet, or on the fly with the
         * current event multicaster in case of a context that is already active.
         * @param listener the ApplicationListener to register
         * @see org.springframework.context.event.ContextRefreshedEvent
         * @see org.springframework.context.event.ContextClosedEvent
         */
        void addApplicationListener(ApplicationListener<?> listener);

        /**
         * Register the given protocol resolver with this application context,
         * allowing for additional resource protocols to be handled.
         * <p>Any such resolver will be invoked ahead of this context's standard
         * resolution rules. It may therefore also override any default rules.
         * @since 4.3
         */
        void addProtocolResolver(ProtocolResolver resolver);

        /**
         * Load or refresh the persistent representation of the configuration, which
         * might be from Java-based configuration, an XML file, a properties file, a
         * relational database schema, or some other format.
         * <p>As this is a startup method, it should destroy already created singletons
         * if it fails, to avoid dangling resources. In other words, after invocation
         * of this method, either all or no singletons at all should be instantiated.
         * @throws BeansException if the bean factory could not be initialized
         * @throws IllegalStateException if already initialized and multiple refresh
         * attempts are not supported
         */
        void refresh() throws BeansException, IllegalStateException;

        /**
         * Register a shutdown hook with the JVM runtime, closing this context
         * on JVM shutdown unless it has already been closed at that time.
         * <p>This method can be called multiple times. Only one shutdown hook
         * (at max) will be registered for each context instance.
         * @see java.lang.Runtime#addShutdownHook
         * @see #close()
         */
        void registerShutdownHook();

        /**
         * Close this application context, releasing all resources and locks that the
         * implementation might hold. This includes destroying all cached singleton beans.
         * <p>Note: Does <i>not</i> invoke {@code close} on a parent context;
         * parent contexts have their own, independent lifecycle.
         * <p>This method can be called multiple times without side effects: Subsequent
         * {@code close} calls on an already closed context will be ignored.
         */
        @Override
        void close();

        /**
         * Determine whether this application context is active, that is,
         * whether it has been refreshed at least once and has not been closed yet.
         * @return whether the context is still active
         * @see #refresh()
         * @see #close()
         * @see #getBeanFactory()
         */
        boolean isActive();

        /**
         * Return the internal bean factory of this application context.
         * Can be used to access specific functionality of the underlying factory.
         * <p>Note: Do not use this to post-process the bean factory; singletons
         * will already have been instantiated before. Use a BeanFactoryPostProcessor
         * to intercept the BeanFactory setup process before beans get touched.
         * <p>Generally, this internal factory will only be accessible while the context
         * is active, that is, in-between {@link #refresh()} and {@link #close()}.
         * The {@link #isActive()} flag can be used to check whether the context
         * is in an appropriate state.
         * @return the underlying bean factory
         * @throws IllegalStateException if the context does not hold an internal
         * bean factory (usually if {@link #refresh()} hasn't been called yet or
         * if {@link #close()} has already been called)
         * @see #isActive()
         * @see #refresh()
         * @see #close()
         * @see #addBeanFactoryPostProcessor
         */
        ConfigurableListableBeanFactory getBeanFactory() throws IllegalStateException;

}