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: * Set the parent of this application context.
041: * <p>Note that the parent shouldn't be changed: It should only be set outside
042: * a constructor if it isn't available when an object of this class is created,
043: * for example in case of WebApplicationContext setup.
044: * @param parent the parent context
045: * @see org.springframework.web.context.ConfigurableWebApplicationContext
046: */
047: void setParent(ApplicationContext parent);
048:
049: /**
050: * Add a new BeanFactoryPostProcessor that will get applied to the internal
051: * bean factory of this application context on refresh, before any of the
052: * bean definitions get evaluated. To be invoked during context configuration.
053: * @param beanFactoryPostProcessor the factory processor to register
054: */
055: void addBeanFactoryPostProcessor(
056: BeanFactoryPostProcessor beanFactoryPostProcessor);
057:
058: /**
059: * Add a new ApplicationListener that will be notified on context events
060: * such as context refresh and context shutdown.
061: * <p>Note that any ApplicationListener registered here will be applied
062: * on refresh of this context. If a listener is added after the initial
063: * refresh, it will be applied on next refresh of the context.
064: * @param listener the ApplicationListener to register
065: * @see org.springframework.context.event.ContextRefreshedEvent
066: * @see org.springframework.context.event.ContextClosedEvent
067: */
068: void addApplicationListener(ApplicationListener listener);
069:
070: /**
071: * Load or refresh the persistent representation of the configuration,
072: * which might an XML file, properties file, or relational database schema.
073: * <p>As this is a startup method, it should destroy already created singletons
074: * if it fails, to avoid dangling resources. In other words, after invocation
075: * of that method, either all or no singletons at all should be instantiated.
076: * @throws BeansException if the bean factory could not be initialized
077: * @throws IllegalStateException if already initialized and multiple refresh
078: * attempts are not supported
079: */
080: void refresh() throws BeansException, IllegalStateException;
081:
082: /**
083: * Register a shutdown hook with the JVM runtime, closing this context
084: * on JVM shutdown unless it has already been closed at that time.
085: * <p>This method can be called multiple times. Only one shutdown hook
086: * (at max) will be registered for each context instance.
087: * @see java.lang.Runtime#addShutdownHook
088: * @see #close()
089: */
090: void registerShutdownHook();
091:
092: /**
093: * Close this application context, releasing all resources and locks that the
094: * implementation might hold. This includes destroying all cached singleton beans.
095: * <p>Note: Does <i>not</i> invoke <code>close</code> on a parent context;
096: * parent contexts have their own, independent lifecycle.
097: * <p>This method can be called multiple times without side effects: Subsequent
098: * <code>close</code> calls on an already closed context will be ignored.
099: */
100: void close();
101:
102: /**
103: * Determine whether this application context is active, that is,
104: * whether it has been refreshed at least once and has not been closed yet.
105: * @return whether the context is still active
106: * @see #refresh()
107: * @see #close()
108: * @see #getBeanFactory()
109: */
110: boolean isActive();
111:
112: /**
113: * Return the internal bean factory of this application context.
114: * Can be used to access specific functionality of the underlying factory.
115: * <p>Note: Do not use this to post-process the bean factory; singletons
116: * will already have been instantiated before. Use a BeanFactoryPostProcessor
117: * to intercept the BeanFactory setup process before beans get touched.
118: * <p>Generally, this internal factory will only be accessible while the context
119: * is active, that is, inbetween {@link #refresh()} and {@link #close()}.
120: * The {@link #isActive()} flag can be used to check whether the context
121: * is in an appropriate state.
122: * @return the underlying bean factory
123: * @throws IllegalStateException if the context does not hold an internal
124: * bean factory (usually if {@link #refresh()} hasn't been called yet or
125: * if {@link #close()} has already been called)
126: * @see #isActive()
127: * @see #refresh()
128: * @see #close()
129: * @see #addBeanFactoryPostProcessor
130: */
131: ConfigurableListableBeanFactory getBeanFactory()
132: throws IllegalStateException;
133:
134: }
|