Open Source Repository

Home /spring/spring-context-3.0.5 | Repository Home


org/springframework/context/ConfigurableApplicationContext.java
/*
 * Copyright 2002-2009 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
 *
 *      http://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 org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;

/**
 * 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
 @since 03.11.2003
 */
public interface ConfigurableApplicationContext extends ApplicationContext, Lifecycle {

  /**
   * 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 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 org.springframework.instrument.classloading.LoadTimeWeaver
   */
  String LOAD_TIME_WEAVER_BEAN_NAME = "loadTimeWeaver";

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

  /**
   * 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 beanFactoryPostProcessor the factory processor to register
   */
  void addBeanFactoryPostProcessor(BeanFactoryPostProcessor beanFactoryPostProcessor);

  /**
   * 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);

  /**
   * Load or refresh the persistent representation of the configuration,
   * which might an XML file, properties file, or relational database schema.
   <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 that 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</code> 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</code> calls on an already closed context will be ignored.
   */
  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, inbetween {@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;

}