org.springframework.context.ConfigurableApplicationContext Maven / Gradle / Ivy
/*
* Copyright 2002-2024 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 java.util.concurrent.Executor;
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
* {@link org.springframework.context.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
* @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 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";
/**
* The name of the {@link Executor bootstrap executor} bean in the context.
* If none is supplied, no background bootstrapping will be active.
* @since 6.2
* @see java.util.concurrent.Executor
* @see org.springframework.core.task.TaskExecutor
* @see org.springframework.beans.factory.support.DefaultListableBeanFactory#setBootstrapExecutor
*/
String BOOTSTRAP_EXECUTOR_BEAN_NAME = "bootstrapExecutor";
/**
* 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";
/**
* Name of the {@link ApplicationStartup} bean in the factory.
* @since 5.3
*/
String APPLICATION_STARTUP_BEAN_NAME = "applicationStartup";
/**
* {@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
*/
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.
* @param parent the parent context
* @see org.springframework.web.context.ConfigurableWebApplicationContext
*/
void setParent(@Nullable 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();
/**
* Set the {@link ApplicationStartup} for this application context.
*
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 {@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.
* @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.
* @param listener the ApplicationListener to register
* @see org.springframework.context.event.ContextRefreshedEvent
* @see org.springframework.context.event.ContextClosedEvent
*/
void addApplicationListener(ApplicationListener listener);
/**
* Remove the given ApplicationListener from this context's set of listeners,
* assuming it got registered via {@link #addApplicationListener} before.
* @param listener the ApplicationListener to deregister
* @since 6.0
*/
void removeApplicationListener(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.
* @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
*/
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
* @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.
*
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 {@code close} on a parent context;
* parent contexts have their own, independent lifecycle.
*
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();
/**
* Return whether this context has been closed already, that is,
* whether {@link #close()} has been called on an active context
* in order to initiate its shutdown.
*
Note: This does not indicate whether context shutdown has completed.
* Use {@link #isActive()} for differentiating between those scenarios:
* a context becomes inactive once it has been fully shut down and the
* original {@code close()} call has returned.
* @since 6.2
*/
boolean isClosed();
/**
* 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 {@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;
}