001: /*
002: * Copyright 2002-2007 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: * http://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:
017: package org.springframework.context;
018:
019: import org.springframework.beans.BeansException;
020: import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
021: import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
022:
023: /**
024: * SPI interface to be implemented by most if not all application contexts.
025: * Provides facilities to configure an application context in addition
026: * to the application context client methods in the
027: * {@link org.springframework.context.ApplicationContext} interface.
028: *
029: * <p>Configuration and lifecycle methods are encapsulated here to avoid
030: * making them obvious to ApplicationContext client code. The present
031: * methods should only be used by startup and shutdown code.
032: *
033: * @author Juergen Hoeller
034: * @since 03.11.2003
035: */
036: public interface ConfigurableApplicationContext extends
037: ApplicationContext, Lifecycle {
038:
039: /**
040: * Name of the LoadTimeWeaver bean in the factory. If such a bean is supplied,
041: * the context will use a temporary ClassLoader for type matching, in order
042: * to allow the LoadTimeWeaver to process all actual bean classes.
043: * @see org.springframework.instrument.classloading.LoadTimeWeaver
044: */
045: String LOAD_TIME_WEAVER_BEAN_NAME = "loadTimeWeaver";
046:
047: /**
048: * Set the parent of this application context.
049: * <p>Note that the parent shouldn't be changed: It should only be set outside
050: * a constructor if it isn't available when an object of this class is created,
051: * for example in case of WebApplicationContext setup.
052: * @param parent the parent context
053: * @see org.springframework.web.context.ConfigurableWebApplicationContext
054: */
055: void setParent(ApplicationContext parent);
056:
057: /**
058: * Add a new BeanFactoryPostProcessor that will get applied to the internal
059: * bean factory of this application context on refresh, before any of the
060: * bean definitions get evaluated. To be invoked during context configuration.
061: * @param beanFactoryPostProcessor the factory processor to register
062: */
063: void addBeanFactoryPostProcessor(
064: BeanFactoryPostProcessor beanFactoryPostProcessor);
065:
066: /**
067: * Add a new ApplicationListener that will be notified on context events
068: * such as context refresh and context shutdown.
069: * <p>Note that any ApplicationListener registered here will be applied
070: * on refresh of this context. If a listener is added after the initial
071: * refresh, it will be applied on next refresh of the context.
072: * @param listener the ApplicationListener to register
073: * @see org.springframework.context.event.ContextRefreshedEvent
074: * @see org.springframework.context.event.ContextClosedEvent
075: */
076: void addApplicationListener(ApplicationListener listener);
077:
078: /**
079: * Load or refresh the persistent representation of the configuration,
080: * which might an XML file, properties file, or relational database schema.
081: * <p>As this is a startup method, it should destroy already created singletons
082: * if it fails, to avoid dangling resources. In other words, after invocation
083: * of that method, either all or no singletons at all should be instantiated.
084: * @throws BeansException if the bean factory could not be initialized
085: * @throws IllegalStateException if already initialized and multiple refresh
086: * attempts are not supported
087: */
088: void refresh() throws BeansException, IllegalStateException;
089:
090: /**
091: * Register a shutdown hook with the JVM runtime, closing this context
092: * on JVM shutdown unless it has already been closed at that time.
093: * <p>This method can be called multiple times. Only one shutdown hook
094: * (at max) will be registered for each context instance.
095: * @see java.lang.Runtime#addShutdownHook
096: * @see #close()
097: */
098: void registerShutdownHook();
099:
100: /**
101: * Close this application context, releasing all resources and locks that the
102: * implementation might hold. This includes destroying all cached singleton beans.
103: * <p>Note: Does <i>not</i> invoke <code>close</code> on a parent context;
104: * parent contexts have their own, independent lifecycle.
105: * <p>This method can be called multiple times without side effects: Subsequent
106: * <code>close</code> calls on an already closed context will be ignored.
107: */
108: void close();
109:
110: /**
111: * Determine whether this application context is active, that is,
112: * whether it has been refreshed at least once and has not been closed yet.
113: * @return whether the context is still active
114: * @see #refresh()
115: * @see #close()
116: * @see #getBeanFactory()
117: */
118: boolean isActive();
119:
120: /**
121: * Return the internal bean factory of this application context.
122: * Can be used to access specific functionality of the underlying factory.
123: * <p>Note: Do not use this to post-process the bean factory; singletons
124: * will already have been instantiated before. Use a BeanFactoryPostProcessor
125: * to intercept the BeanFactory setup process before beans get touched.
126: * <p>Generally, this internal factory will only be accessible while the context
127: * is active, that is, inbetween {@link #refresh()} and {@link #close()}.
128: * The {@link #isActive()} flag can be used to check whether the context
129: * is in an appropriate state.
130: * @return the underlying bean factory
131: * @throws IllegalStateException if the context does not hold an internal
132: * bean factory (usually if {@link #refresh()} hasn't been called yet or
133: * if {@link #close()} has already been called)
134: * @see #isActive()
135: * @see #refresh()
136: * @see #close()
137: * @see #addBeanFactoryPostProcessor
138: */
139: ConfigurableListableBeanFactory getBeanFactory()
140: throws IllegalStateException;
141:
142: }
|