001/* 002 * Copyright 2002-2019 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>This annotation may be used as a <em>meta-annotation</em> to create custom 037 * <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.DirtiesContextBeforeModesTestExecutionListener 066 * @see org.springframework.test.context.support.DependencyInjectionTestExecutionListener 067 * @see org.springframework.test.context.support.DirtiesContextTestExecutionListener 068 * @see org.springframework.test.context.transaction.TransactionalTestExecutionListener 069 * @see org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener 070 * @see org.springframework.test.context.event.EventPublishingTestExecutionListener 071 */ 072 @AliasFor("value") 073 Class<? extends TestExecutionListener>[] listeners() default {}; 074 075 /** 076 * Whether or not {@link #listeners TestExecutionListeners} from superclasses 077 * should be <em>inherited</em>. 078 * <p>The default value is {@code true}, which means that an annotated 079 * class will <em>inherit</em> the listeners defined by an annotated 080 * superclass. Specifically, the listeners for an annotated class will be 081 * appended to the list of listeners defined by an annotated superclass. 082 * Thus, subclasses have the option of <em>extending</em> the list of 083 * listeners. In the following example, {@code AbstractBaseTest} will 084 * be configured with {@code DependencyInjectionTestExecutionListener} 085 * and {@code DirtiesContextTestExecutionListener}; whereas, 086 * {@code TransactionalTest} will be configured with 087 * {@code DependencyInjectionTestExecutionListener}, 088 * {@code DirtiesContextTestExecutionListener}, <strong>and</strong> 089 * {@code TransactionalTestExecutionListener}, in that order. 090 * <pre class="code"> 091 * @TestExecutionListeners({ 092 * DependencyInjectionTestExecutionListener.class, 093 * DirtiesContextTestExecutionListener.class 094 * }) 095 * public abstract class AbstractBaseTest { 096 * // ... 097 * } 098 * 099 * @TestExecutionListeners(TransactionalTestExecutionListener.class) 100 * public class TransactionalTest extends AbstractBaseTest { 101 * // ... 102 * }</pre> 103 * <p>If {@code inheritListeners} is set to {@code false}, the listeners for 104 * the annotated class will <em>shadow</em> and effectively replace any 105 * listeners defined by a superclass. 106 */ 107 boolean inheritListeners() default true; 108 109 /** 110 * The <em>merge mode</em> to use when {@code @TestExecutionListeners} is 111 * declared on a class that does <strong>not</strong> inherit listeners 112 * from a superclass. 113 * <p>Can be set to {@link MergeMode#MERGE_WITH_DEFAULTS MERGE_WITH_DEFAULTS} 114 * to have locally declared listeners <em>merged</em> with the default 115 * listeners. 116 * <p>The mode is ignored if listeners are inherited from a superclass. 117 * <p>Defaults to {@link MergeMode#REPLACE_DEFAULTS REPLACE_DEFAULTS} 118 * for backwards compatibility. 119 * @see MergeMode 120 * @since 4.1 121 */ 122 MergeMode mergeMode() default MergeMode.REPLACE_DEFAULTS; 123 124 125 /** 126 * Enumeration of <em>modes</em> that dictate whether or not explicitly 127 * declared listeners are merged with the default listeners when 128 * {@code @TestExecutionListeners} is declared on a class that does 129 * <strong>not</strong> inherit listeners from a superclass. 130 * @since 4.1 131 */ 132 enum MergeMode { 133 134 /** 135 * Indicates that locally declared listeners should replace the default 136 * listeners. 137 */ 138 REPLACE_DEFAULTS, 139 140 /** 141 * Indicates that locally declared listeners should be merged with the 142 * default listeners. 143 * <p>The merging algorithm ensures that duplicates are removed from 144 * the list and that the resulting set of merged listeners is sorted 145 * according to the semantics of 146 * {@link org.springframework.core.annotation.AnnotationAwareOrderComparator 147 * AnnotationAwareOrderComparator}. If a listener implements 148 * {@link org.springframework.core.Ordered Ordered} or is annotated 149 * with {@link org.springframework.core.annotation.Order @Order} it can 150 * influence the position in which it is merged with the defaults; otherwise, 151 * locally declared listeners will simply be appended to the list of default 152 * listeners when merged. 153 */ 154 MERGE_WITH_DEFAULTS 155 } 156 157}