001/*
002 * Copyright 2002-2014 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.context;
018
019import org.springframework.beans.factory.HierarchicalBeanFactory;
020import org.springframework.beans.factory.ListableBeanFactory;
021import org.springframework.beans.factory.config.AutowireCapableBeanFactory;
022import org.springframework.core.env.EnvironmentCapable;
023import org.springframework.core.io.support.ResourcePatternResolver;
024import org.springframework.lang.Nullable;
025
026/**
027 * Central interface to provide configuration for an application.
028 * This is read-only while the application is running, but may be
029 * reloaded if the implementation supports this.
030 *
031 * <p>An ApplicationContext provides:
032 * <ul>
033 * <li>Bean factory methods for accessing application components.
034 * Inherited from {@link org.springframework.beans.factory.ListableBeanFactory}.
035 * <li>The ability to load file resources in a generic fashion.
036 * Inherited from the {@link org.springframework.core.io.ResourceLoader} interface.
037 * <li>The ability to publish events to registered listeners.
038 * Inherited from the {@link ApplicationEventPublisher} interface.
039 * <li>The ability to resolve messages, supporting internationalization.
040 * Inherited from the {@link MessageSource} interface.
041 * <li>Inheritance from a parent context. Definitions in a descendant context
042 * will always take priority. This means, for example, that a single parent
043 * context can be used by an entire web application, while each servlet has
044 * its own child context that is independent of that of any other servlet.
045 * </ul>
046 *
047 * <p>In addition to standard {@link org.springframework.beans.factory.BeanFactory}
048 * lifecycle capabilities, ApplicationContext implementations detect and invoke
049 * {@link ApplicationContextAware} beans as well as {@link ResourceLoaderAware},
050 * {@link ApplicationEventPublisherAware} and {@link MessageSourceAware} beans.
051 *
052 * @author Rod Johnson
053 * @author Juergen Hoeller
054 * @see ConfigurableApplicationContext
055 * @see org.springframework.beans.factory.BeanFactory
056 * @see org.springframework.core.io.ResourceLoader
057 */
058public interface ApplicationContext extends EnvironmentCapable, ListableBeanFactory, HierarchicalBeanFactory,
059                MessageSource, ApplicationEventPublisher, ResourcePatternResolver {
060
061        /**
062         * Return the unique id of this application context.
063         * @return the unique id of the context, or {@code null} if none
064         */
065        @Nullable
066        String getId();
067
068        /**
069         * Return a name for the deployed application that this context belongs to.
070         * @return a name for the deployed application, or the empty String by default
071         */
072        String getApplicationName();
073
074        /**
075         * Return a friendly name for this context.
076         * @return a display name for this context (never {@code null})
077         */
078        String getDisplayName();
079
080        /**
081         * Return the timestamp when this context was first loaded.
082         * @return the timestamp (ms) when this context was first loaded
083         */
084        long getStartupDate();
085
086        /**
087         * Return the parent context, or {@code null} if there is no parent
088         * and this is the root of the context hierarchy.
089         * @return the parent context, or {@code null} if there is no parent
090         */
091        @Nullable
092        ApplicationContext getParent();
093
094        /**
095         * Expose AutowireCapableBeanFactory functionality for this context.
096         * <p>This is not typically used by application code, except for the purpose of
097         * initializing bean instances that live outside of the application context,
098         * applying the Spring bean lifecycle (fully or partly) to them.
099         * <p>Alternatively, the internal BeanFactory exposed by the
100         * {@link ConfigurableApplicationContext} interface offers access to the
101         * {@link AutowireCapableBeanFactory} interface too. The present method mainly
102         * serves as a convenient, specific facility on the ApplicationContext interface.
103         * <p><b>NOTE: As of 4.2, this method will consistently throw IllegalStateException
104         * after the application context has been closed.</b> In current Spring Framework
105         * versions, only refreshable application contexts behave that way; as of 4.2,
106         * all application context implementations will be required to comply.
107         * @return the AutowireCapableBeanFactory for this context
108         * @throws IllegalStateException if the context does not support the
109         * {@link AutowireCapableBeanFactory} interface, or does not hold an
110         * autowire-capable bean factory yet (e.g. if {@code refresh()} has
111         * never been called), or if the context has been closed already
112         * @see ConfigurableApplicationContext#refresh()
113         * @see ConfigurableApplicationContext#getBeanFactory()
114         */
115        AutowireCapableBeanFactory getAutowireCapableBeanFactory() throws IllegalStateException;
116
117}