https://github.com/spring-projects/spring-framework: Spring Context (Spring IO)
  • Juergen Hoeller 
/*
 * 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;
import org.springframework.core.metrics.ApplicationStartup;
import org.springframework.lang.Nullable;


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 ApplicationContext interface. 
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, Chris Beams, Sam Brannen
Since:03.11.2003
/**
 * 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
 * @author Sam Brannen
 * @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 Also:
  • setConfigLocation.setConfigLocation
  • CONFIG_LOCATION_PARAM.CONFIG_LOCATION_PARAM
  • setContextConfigLocation.setContextConfigLocation
/**
	 * 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.

See Also:
Since:3.0
/**
	 * 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.

See Also:
Since:2.5
/**
	 * 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 Environment bean in the factory. 
Since:3.1
/**
	 * 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 Also:
  • getProperties.getProperties()
/**
	 * 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 Also:
  • getenv.getenv()
/**
	 * Name of the System environment bean in the factory.
	 * @see java.lang.System#getenv()
	 */
	String SYSTEM_ENVIRONMENT_BEAN_NAME = "systemEnvironment";

	
Name of the ApplicationStartup bean in the factory. 
Since:5.3
/**
	 * Name of the {@link ApplicationStartup} bean in the factory.
	 * @since 5.3
	 */
	String APPLICATION_STARTUP_BEAN_NAME = "applicationStartup";

	
Name of the 
shutdown hook thread: "SpringContextShutdownHook". 
See Also:
Since:5.2
/**
	 * {@link Thread#getName() Name} of the {@linkplain #registerShutdownHook()
	 * shutdown hook} thread: {@value}.
	 * @since 5.2
	 * @see #registerShutdownHook()
	 */
	String SHUTDOWN_HOOK_THREAD_NAME = "SpringContextShutdownHook";


	
Set the unique id of this application context.

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

	
Set the parent of this application context.

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.

Params:
  • parent – the parent context
See Also:
  • ConfigurableWebApplicationContext
/**
	 * 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(@Nullable ApplicationContext parent);

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

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

	
Set the ApplicationStartup for this application context. 
This allows the application context to record metrics
during startup.

Params:
  • applicationStartup – the new context event factory
Since:5.3
/**
	 * Set the {@link ApplicationStartup} for this application context.
	 * <p>This allows the application context to record metrics
	 * during startup.
	 * @param applicationStartup the new context event factory
	 * @since 5.3
	 */
	void setApplicationStartup(ApplicationStartup applicationStartup);

	
Return the ApplicationStartup for this application context. 
Since:5.3
/**
	 * Return the {@link ApplicationStartup} for this application context.
	 * @since 5.3
	 */
	ApplicationStartup getApplicationStartup();

	
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.

Params:
  • postProcessor – the factory processor to register
/**
	 * 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.

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.

Params:
  • listener – the ApplicationListener to register
See Also:
/**
	 * 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);

	
Specify the ClassLoader to load class path resources and bean classes with.

This context class loader will be passed to the internal bean factory.

See Also:
Since:5.2.7
/**
	 * Specify the ClassLoader to load class path resources and bean classes with.
	 * <p>This context class loader will be passed to the internal bean factory.
	 * @since 5.2.7
	 * @see org.springframework.core.io.DefaultResourceLoader#DefaultResourceLoader(ClassLoader)
	 * @see org.springframework.beans.factory.config.ConfigurableBeanFactory#setBeanClassLoader
	 */
	void setClassLoader(ClassLoader classLoader);

	
Register the given protocol resolver with this application context,
allowing for additional resource protocols to be handled.

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
/**
	 * 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.

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
  • IllegalStateException – if already initialized and multiple refresh
attempts are not supported
/**
	 * 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.

This method can be called multiple times. Only one shutdown hook
(at max) will be registered for each context instance.

As of Spring Framework 5.2, the name of the shutdown hook thread should be SHUTDOWN_HOOK_THREAD_NAME. 
See Also:
/**
	 * 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.
	 * <p>As of Spring Framework 5.2, the {@linkplain Thread#getName() name} of
	 * the shutdown hook thread should be {@link #SHUTDOWN_HOOK_THREAD_NAME}.
	 * @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.

Note: Does not invoke close on a parent context; parent contexts have their own, independent lifecycle. 
This method can be called multiple times without side effects: Subsequent close calls on an already closed context will be ignored. 
/**
	 * 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.

See Also:
Returns:whether the context is still active
/**
	 * 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.

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.

Generally, this internal factory will only be accessible while the context is active, that is, in-between refresh() and close(). The isActive() flag can be used to check whether the context is in an appropriate state. 
Throws:
See Also:
Returns:the underlying bean factory
/**
	 * 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;

}