001/* 002 * Copyright 2002-2016 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 java.lang.annotation.Documented; 020import java.lang.annotation.ElementType; 021import java.lang.annotation.Inherited; 022import java.lang.annotation.Retention; 023import java.lang.annotation.RetentionPolicy; 024import java.lang.annotation.Target; 025 026import org.springframework.core.annotation.AliasFor; 027 028/** 029 * {@code TestExecutionListeners} defines class-level metadata for configuring 030 * which {@link TestExecutionListener TestExecutionListeners} should be 031 * registered with a {@link TestContextManager}. 032 * 033 * <p>Typically, {@code @TestExecutionListeners} will be used in conjunction 034 * with {@link ContextConfiguration @ContextConfiguration}. 035 * 036 * <p>As of Spring Framework 4.0, this annotation may be used as a 037 * <em>meta-annotation</em> to create custom <em>composed annotations</em>. 038 * 039 * @author Sam Brannen 040 * @since 2.5 041 * @see TestExecutionListener 042 * @see TestContextManager 043 * @see ContextConfiguration 044 */ 045@Target(ElementType.TYPE) 046@Retention(RetentionPolicy.RUNTIME) 047@Documented 048@Inherited 049public @interface TestExecutionListeners { 050 051 /** 052 * Alias for {@link #listeners}. 053 * <p>This attribute may <strong>not</strong> be used in conjunction with 054 * {@link #listeners}, but it may be used instead of {@link #listeners}. 055 */ 056 @AliasFor("listeners") 057 Class<? extends TestExecutionListener>[] value() default {}; 058 059 /** 060 * The {@link TestExecutionListener TestExecutionListeners} to register with 061 * the {@link TestContextManager}. 062 * <p>This attribute may <strong>not</strong> be used in conjunction with 063 * {@link #value}, but it may be used instead of {@link #value}. 064 * @see org.springframework.test.context.web.ServletTestExecutionListener 065 * @see org.springframework.test.context.support.DependencyInjectionTestExecutionListener 066 * @see org.springframework.test.context.support.DirtiesContextTestExecutionListener 067 * @see org.springframework.test.context.transaction.TransactionalTestExecutionListener 068 * @see org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener 069 */ 070 @AliasFor("value") 071 Class<? extends TestExecutionListener>[] listeners() default {}; 072 073 /** 074 * Whether or not {@link #listeners TestExecutionListeners} from superclasses 075 * should be <em>inherited</em>. 076 * <p>The default value is {@code true}, which means that an annotated 077 * class will <em>inherit</em> the listeners defined by an annotated 078 * superclass. Specifically, the listeners for an annotated class will be 079 * appended to the list of listeners defined by an annotated superclass. 080 * Thus, subclasses have the option of <em>extending</em> the list of 081 * listeners. In the following example, {@code AbstractBaseTest} will 082 * be configured with {@code DependencyInjectionTestExecutionListener} 083 * and {@code DirtiesContextTestExecutionListener}; whereas, 084 * {@code TransactionalTest} will be configured with 085 * {@code DependencyInjectionTestExecutionListener}, 086 * {@code DirtiesContextTestExecutionListener}, <strong>and</strong> 087 * {@code TransactionalTestExecutionListener}, in that order. 088 * <pre class="code"> 089 * @TestExecutionListeners({ 090 * DependencyInjectionTestExecutionListener.class, 091 * DirtiesContextTestExecutionListener.class 092 * }) 093 * public abstract class AbstractBaseTest { 094 * // ... 095 * } 096 * 097 * @TestExecutionListeners(TransactionalTestExecutionListener.class) 098 * public class TransactionalTest extends AbstractBaseTest { 099 * // ... 100 * }</pre> 101 * <p>If {@code inheritListeners} is set to {@code false}, the listeners for 102 * the annotated class will <em>shadow</em> and effectively replace any 103 * listeners defined by a superclass. 104 */ 105 boolean inheritListeners() default true; 106 107 /** 108 * The <em>merge mode</em> to use when {@code @TestExecutionListeners} is 109 * declared on a class that does <strong>not</strong> inherit listeners 110 * from a superclass. 111 * <p>Can be set to {@link MergeMode#MERGE_WITH_DEFAULTS MERGE_WITH_DEFAULTS} 112 * to have locally declared listeners <em>merged</em> with the default 113 * listeners. 114 * <p>The mode is ignored if listeners are inherited from a superclass. 115 * <p>Defaults to {@link MergeMode#REPLACE_DEFAULTS REPLACE_DEFAULTS} 116 * for backwards compatibility. 117 * @see MergeMode 118 * @since 4.1 119 */ 120 MergeMode mergeMode() default MergeMode.REPLACE_DEFAULTS; 121 122 123 /** 124 * Enumeration of <em>modes</em> that dictate whether or not explicitly 125 * declared listeners are merged with the default listeners when 126 * {@code @TestExecutionListeners} is declared on a class that does 127 * <strong>not</strong> inherit listeners from a superclass. 128 * @since 4.1 129 */ 130 enum MergeMode { 131 132 /** 133 * Indicates that locally declared listeners should replace the default 134 * listeners. 135 */ 136 REPLACE_DEFAULTS, 137 138 /** 139 * Indicates that locally declared listeners should be merged with the 140 * default listeners. 141 * <p>The merging algorithm ensures that duplicates are removed from 142 * the list and that the resulting set of merged listeners is sorted 143 * according to the semantics of 144 * {@link org.springframework.core.annotation.AnnotationAwareOrderComparator 145 * AnnotationAwareOrderComparator}. If a listener implements 146 * {@link org.springframework.core.Ordered Ordered} or is annotated 147 * with {@link org.springframework.core.annotation.Order @Order} it can 148 * influence the position in which it is merged with the defaults; otherwise, 149 * locally declared listeners will simply be appended to the list of default 150 * listeners when merged. 151 */ 152 MERGE_WITH_DEFAULTS 153 } 154 155}