001/*
002 * Copyright 2002-2015 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.test.context;
018
019import org.springframework.context.ApplicationContext;
020
021/**
022 * Strategy interface for loading an {@link ApplicationContext application context}
023 * for an integration test managed by the Spring TestContext Framework.
024 *
025 * <p><b>Note</b>: as of Spring 3.1, implement {@link SmartContextLoader} instead
026 * of this interface in order to provide support for annotated classes, active
027 * bean definition profiles, and application context initializers.
028 *
029 * <p>Clients of a ContextLoader should call
030 * {@link #processLocations(Class, String...) processLocations()} prior to
031 * calling {@link #loadContext(String...) loadContext()} in case the
032 * ContextLoader provides custom support for modifying or generating locations.
033 * The results of {@link #processLocations(Class, String...) processLocations()}
034 * should then be supplied to {@link #loadContext(String...) loadContext()}.
035 *
036 * <p>Concrete implementations must provide a {@code public} no-args constructor.
037 *
038 * <p>Spring provides the following out-of-the-box implementations:
039 * <ul>
040 * <li>{@link org.springframework.test.context.support.GenericXmlContextLoader GenericXmlContextLoader}</li>
041 * <li>{@link org.springframework.test.context.support.GenericPropertiesContextLoader GenericPropertiesContextLoader}</li>
042 * </ul>
043 *
044 * @author Sam Brannen
045 * @author Juergen Hoeller
046 * @since 2.5
047 * @see SmartContextLoader
048 * @see org.springframework.test.context.support.AnnotationConfigContextLoader AnnotationConfigContextLoader
049 */
050public interface ContextLoader {
051
052        /**
053         * Processes application context resource locations for a specified class.
054         * <p>Concrete implementations may choose to modify the supplied locations,
055         * generate new locations, or simply return the supplied locations unchanged.
056         * @param clazz the class with which the locations are associated: used to
057         * determine how to process the supplied locations
058         * @param locations the unmodified locations to use for loading the
059         * application context (can be {@code null} or empty)
060         * @return an array of application context resource locations
061         */
062        String[] processLocations(Class<?> clazz, String... locations);
063
064        /**
065         * Loads a new {@link ApplicationContext context} based on the supplied
066         * {@code locations}, configures the context, and finally returns
067         * the context in fully <em>refreshed</em> state.
068         * <p>Configuration locations are generally considered to be classpath
069         * resources by default.
070         * <p>Concrete implementations should register annotation configuration
071         * processors with bean factories of {@link ApplicationContext application
072         * contexts} loaded by this ContextLoader. Beans will therefore automatically
073         * be candidates for annotation-based dependency injection using
074         * {@link org.springframework.beans.factory.annotation.Autowired @Autowired},
075         * {@link javax.annotation.Resource @Resource}, and
076         * {@link javax.inject.Inject @Inject}.
077         * <p>Any ApplicationContext loaded by a ContextLoader <strong>must</strong>
078         * register a JVM shutdown hook for itself. Unless the context gets closed
079         * early, all context instances will be automatically closed on JVM
080         * shutdown. This allows for freeing external resources held by beans within
081         * the context, e.g. temporary files.
082         * @param locations the resource locations to use to load the application context
083         * @return a new application context
084         * @throws Exception if context loading failed
085         */
086        ApplicationContext loadContext(String... locations) throws Exception;
087
088}