001/* 002 * Copyright 2002-2020 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 java.io.Closeable; 020 021import org.springframework.beans.BeansException; 022import org.springframework.beans.factory.config.BeanFactoryPostProcessor; 023import org.springframework.beans.factory.config.ConfigurableListableBeanFactory; 024import org.springframework.core.env.ConfigurableEnvironment; 025import org.springframework.core.env.Environment; 026import org.springframework.core.io.ProtocolResolver; 027import org.springframework.lang.Nullable; 028 029/** 030 * SPI interface to be implemented by most if not all application contexts. 031 * Provides facilities to configure an application context in addition 032 * to the application context client methods in the 033 * {@link org.springframework.context.ApplicationContext} interface. 034 * 035 * <p>Configuration and lifecycle methods are encapsulated here to avoid 036 * making them obvious to ApplicationContext client code. The present 037 * methods should only be used by startup and shutdown code. 038 * 039 * @author Juergen Hoeller 040 * @author Chris Beams 041 * @author Sam Brannen 042 * @since 03.11.2003 043 */ 044public interface ConfigurableApplicationContext extends ApplicationContext, Lifecycle, Closeable { 045 046 /** 047 * Any number of these characters are considered delimiters between 048 * multiple context config paths in a single String value. 049 * @see org.springframework.context.support.AbstractXmlApplicationContext#setConfigLocation 050 * @see org.springframework.web.context.ContextLoader#CONFIG_LOCATION_PARAM 051 * @see org.springframework.web.servlet.FrameworkServlet#setContextConfigLocation 052 */ 053 String CONFIG_LOCATION_DELIMITERS = ",; \t\n"; 054 055 /** 056 * Name of the ConversionService bean in the factory. 057 * If none is supplied, default conversion rules apply. 058 * @since 3.0 059 * @see org.springframework.core.convert.ConversionService 060 */ 061 String CONVERSION_SERVICE_BEAN_NAME = "conversionService"; 062 063 /** 064 * Name of the LoadTimeWeaver bean in the factory. If such a bean is supplied, 065 * the context will use a temporary ClassLoader for type matching, in order 066 * to allow the LoadTimeWeaver to process all actual bean classes. 067 * @since 2.5 068 * @see org.springframework.instrument.classloading.LoadTimeWeaver 069 */ 070 String LOAD_TIME_WEAVER_BEAN_NAME = "loadTimeWeaver"; 071 072 /** 073 * Name of the {@link Environment} bean in the factory. 074 * @since 3.1 075 */ 076 String ENVIRONMENT_BEAN_NAME = "environment"; 077 078 /** 079 * Name of the System properties bean in the factory. 080 * @see java.lang.System#getProperties() 081 */ 082 String SYSTEM_PROPERTIES_BEAN_NAME = "systemProperties"; 083 084 /** 085 * Name of the System environment bean in the factory. 086 * @see java.lang.System#getenv() 087 */ 088 String SYSTEM_ENVIRONMENT_BEAN_NAME = "systemEnvironment"; 089 090 /** 091 * {@link Thread#getName() Name} of the {@linkplain #registerShutdownHook() 092 * shutdown hook} thread: {@value}. 093 * @since 5.2 094 * @see #registerShutdownHook() 095 */ 096 String SHUTDOWN_HOOK_THREAD_NAME = "SpringContextShutdownHook"; 097 098 099 /** 100 * Set the unique id of this application context. 101 * @since 3.0 102 */ 103 void setId(String id); 104 105 /** 106 * Set the parent of this application context. 107 * <p>Note that the parent shouldn't be changed: It should only be set outside 108 * a constructor if it isn't available when an object of this class is created, 109 * for example in case of WebApplicationContext setup. 110 * @param parent the parent context 111 * @see org.springframework.web.context.ConfigurableWebApplicationContext 112 */ 113 void setParent(@Nullable ApplicationContext parent); 114 115 /** 116 * Set the {@code Environment} for this application context. 117 * @param environment the new environment 118 * @since 3.1 119 */ 120 void setEnvironment(ConfigurableEnvironment environment); 121 122 /** 123 * Return the {@code Environment} for this application context in configurable 124 * form, allowing for further customization. 125 * @since 3.1 126 */ 127 @Override 128 ConfigurableEnvironment getEnvironment(); 129 130 /** 131 * Add a new BeanFactoryPostProcessor that will get applied to the internal 132 * bean factory of this application context on refresh, before any of the 133 * bean definitions get evaluated. To be invoked during context configuration. 134 * @param postProcessor the factory processor to register 135 */ 136 void addBeanFactoryPostProcessor(BeanFactoryPostProcessor postProcessor); 137 138 /** 139 * Add a new ApplicationListener that will be notified on context events 140 * such as context refresh and context shutdown. 141 * <p>Note that any ApplicationListener registered here will be applied 142 * on refresh if the context is not active yet, or on the fly with the 143 * current event multicaster in case of a context that is already active. 144 * @param listener the ApplicationListener to register 145 * @see org.springframework.context.event.ContextRefreshedEvent 146 * @see org.springframework.context.event.ContextClosedEvent 147 */ 148 void addApplicationListener(ApplicationListener<?> listener); 149 150 /** 151 * Specify the ClassLoader to load class path resources and bean classes with. 152 * <p>This context class loader will be passed to the internal bean factory. 153 * @since 5.2.7 154 * @see org.springframework.core.io.DefaultResourceLoader#DefaultResourceLoader(ClassLoader) 155 * @see org.springframework.beans.factory.config.ConfigurableBeanFactory#setBeanClassLoader 156 */ 157 void setClassLoader(ClassLoader classLoader); 158 159 /** 160 * Register the given protocol resolver with this application context, 161 * allowing for additional resource protocols to be handled. 162 * <p>Any such resolver will be invoked ahead of this context's standard 163 * resolution rules. It may therefore also override any default rules. 164 * @since 4.3 165 */ 166 void addProtocolResolver(ProtocolResolver resolver); 167 168 /** 169 * Load or refresh the persistent representation of the configuration, which 170 * might be from Java-based configuration, an XML file, a properties file, a 171 * relational database schema, or some other format. 172 * <p>As this is a startup method, it should destroy already created singletons 173 * if it fails, to avoid dangling resources. In other words, after invocation 174 * of this method, either all or no singletons at all should be instantiated. 175 * @throws BeansException if the bean factory could not be initialized 176 * @throws IllegalStateException if already initialized and multiple refresh 177 * attempts are not supported 178 */ 179 void refresh() throws BeansException, IllegalStateException; 180 181 /** 182 * Register a shutdown hook with the JVM runtime, closing this context 183 * on JVM shutdown unless it has already been closed at that time. 184 * <p>This method can be called multiple times. Only one shutdown hook 185 * (at max) will be registered for each context instance. 186 * <p>As of Spring Framework 5.2, the {@linkplain Thread#getName() name} of 187 * the shutdown hook thread should be {@link #SHUTDOWN_HOOK_THREAD_NAME}. 188 * @see java.lang.Runtime#addShutdownHook 189 * @see #close() 190 */ 191 void registerShutdownHook(); 192 193 /** 194 * Close this application context, releasing all resources and locks that the 195 * implementation might hold. This includes destroying all cached singleton beans. 196 * <p>Note: Does <i>not</i> invoke {@code close} on a parent context; 197 * parent contexts have their own, independent lifecycle. 198 * <p>This method can be called multiple times without side effects: Subsequent 199 * {@code close} calls on an already closed context will be ignored. 200 */ 201 @Override 202 void close(); 203 204 /** 205 * Determine whether this application context is active, that is, 206 * whether it has been refreshed at least once and has not been closed yet. 207 * @return whether the context is still active 208 * @see #refresh() 209 * @see #close() 210 * @see #getBeanFactory() 211 */ 212 boolean isActive(); 213 214 /** 215 * Return the internal bean factory of this application context. 216 * Can be used to access specific functionality of the underlying factory. 217 * <p>Note: Do not use this to post-process the bean factory; singletons 218 * will already have been instantiated before. Use a BeanFactoryPostProcessor 219 * to intercept the BeanFactory setup process before beans get touched. 220 * <p>Generally, this internal factory will only be accessible while the context 221 * is active, that is, in-between {@link #refresh()} and {@link #close()}. 222 * The {@link #isActive()} flag can be used to check whether the context 223 * is in an appropriate state. 224 * @return the underlying bean factory 225 * @throws IllegalStateException if the context does not hold an internal 226 * bean factory (usually if {@link #refresh()} hasn't been called yet or 227 * if {@link #close()} has already been called) 228 * @see #isActive() 229 * @see #refresh() 230 * @see #close() 231 * @see #addBeanFactoryPostProcessor 232 */ 233 ConfigurableListableBeanFactory getBeanFactory() throws IllegalStateException; 234 235}