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.jdbc; 018 019import java.lang.annotation.Documented; 020import java.lang.annotation.ElementType; 021import java.lang.annotation.Inherited; 022import java.lang.annotation.Repeatable; 023import java.lang.annotation.Retention; 024import java.lang.annotation.RetentionPolicy; 025import java.lang.annotation.Target; 026 027import org.springframework.core.annotation.AliasFor; 028 029/** 030 * {@code @Sql} is used to annotate a test class or test method to configure 031 * SQL {@link #scripts} and {@link #statements} to be executed against a given 032 * database during integration tests. 033 * 034 * <p>Method-level declarations override class-level declarations by default, 035 * but this behavior can be configured via {@link SqlMergeMode @SqlMergeMode}. 036 * 037 * <p>Script execution is performed by the {@link SqlScriptsTestExecutionListener}, 038 * which is enabled by default. 039 * 040 * <p>The configuration options provided by this annotation and 041 * {@link SqlConfig @SqlConfig} are equivalent to those supported by 042 * {@link org.springframework.jdbc.datasource.init.ScriptUtils ScriptUtils} and 043 * {@link org.springframework.jdbc.datasource.init.ResourceDatabasePopulator ResourceDatabasePopulator} 044 * but are a superset of those provided by the {@code <jdbc:initialize-database/>} 045 * XML namespace element. Consult the javadocs of individual attributes in this 046 * annotation and {@link SqlConfig @SqlConfig} for details. 047 * 048 * <p>Beginning with Java 8, {@code @Sql} can be used as a 049 * <em>{@linkplain Repeatable repeatable}</em> annotation. Otherwise, 050 * {@link SqlGroup @SqlGroup} can be used as an explicit container for declaring 051 * multiple instances of {@code @Sql}. 052 * 053 * <p>This annotation may be used as a <em>meta-annotation</em> to create custom 054 * <em>composed annotations</em> with attribute overrides. 055 * 056 * @author Sam Brannen 057 * @since 4.1 058 * @see SqlConfig 059 * @see SqlMergeMode 060 * @see SqlGroup 061 * @see SqlScriptsTestExecutionListener 062 * @see org.springframework.transaction.annotation.Transactional 063 * @see org.springframework.test.context.transaction.TransactionalTestExecutionListener 064 * @see org.springframework.jdbc.datasource.init.ResourceDatabasePopulator 065 * @see org.springframework.jdbc.datasource.init.ScriptUtils 066 */ 067@Target({ElementType.TYPE, ElementType.METHOD}) 068@Retention(RetentionPolicy.RUNTIME) 069@Documented 070@Inherited 071@Repeatable(SqlGroup.class) 072public @interface Sql { 073 074 /** 075 * Alias for {@link #scripts}. 076 * <p>This attribute may <strong>not</strong> be used in conjunction with 077 * {@link #scripts}, but it may be used instead of {@link #scripts}. 078 * @see #scripts 079 * @see #statements 080 */ 081 @AliasFor("scripts") 082 String[] value() default {}; 083 084 /** 085 * The paths to the SQL scripts to execute. 086 * <p>This attribute may <strong>not</strong> be used in conjunction with 087 * {@link #value}, but it may be used instead of {@link #value}. Similarly, 088 * this attribute may be used in conjunction with or instead of 089 * {@link #statements}. 090 * <h3>Path Resource Semantics</h3> 091 * <p>Each path will be interpreted as a Spring 092 * {@link org.springframework.core.io.Resource Resource}. A plain path 093 * — for example, {@code "schema.sql"} — will be treated as a 094 * classpath resource that is <em>relative</em> to the package in which the 095 * test class is defined. A path starting with a slash will be treated as an 096 * <em>absolute</em> classpath resource, for example: 097 * {@code "/org/example/schema.sql"}. A path which references a 098 * URL (e.g., a path prefixed with 099 * {@link org.springframework.util.ResourceUtils#CLASSPATH_URL_PREFIX classpath:}, 100 * {@link org.springframework.util.ResourceUtils#FILE_URL_PREFIX file:}, 101 * {@code http:}, etc.) will be loaded using the specified resource protocol. 102 * <h3>Default Script Detection</h3> 103 * <p>If no SQL scripts or {@link #statements} are specified, an attempt will 104 * be made to detect a <em>default</em> script depending on where this 105 * annotation is declared. If a default cannot be detected, an 106 * {@link IllegalStateException} will be thrown. 107 * <ul> 108 * <li><strong>class-level declaration</strong>: if the annotated test class 109 * is {@code com.example.MyTest}, the corresponding default script is 110 * {@code "classpath:com/example/MyTest.sql"}.</li> 111 * <li><strong>method-level declaration</strong>: if the annotated test 112 * method is named {@code testMethod()} and is defined in the class 113 * {@code com.example.MyTest}, the corresponding default script is 114 * {@code "classpath:com/example/MyTest.testMethod.sql"}.</li> 115 * </ul> 116 * @see #value 117 * @see #statements 118 */ 119 @AliasFor("value") 120 String[] scripts() default {}; 121 122 /** 123 * <em>Inlined SQL statements</em> to execute. 124 * <p>This attribute may be used in conjunction with or instead of 125 * {@link #scripts}. 126 * <h3>Ordering</h3> 127 * <p>Statements declared via this attribute will be executed after 128 * statements loaded from resource {@link #scripts}. If you wish to have 129 * inlined statements executed before scripts, simply declare multiple 130 * instances of {@code @Sql} on the same class or method. 131 * @since 4.2 132 * @see #scripts 133 */ 134 String[] statements() default {}; 135 136 /** 137 * When the SQL scripts and statements should be executed. 138 * <p>Defaults to {@link ExecutionPhase#BEFORE_TEST_METHOD BEFORE_TEST_METHOD}. 139 */ 140 ExecutionPhase executionPhase() default ExecutionPhase.BEFORE_TEST_METHOD; 141 142 /** 143 * Local configuration for the SQL scripts and statements declared within 144 * this {@code @Sql} annotation. 145 * <p>See the class-level javadocs for {@link SqlConfig} for explanations of 146 * local vs. global configuration, inheritance, overrides, etc. 147 * <p>Defaults to an empty {@link SqlConfig @SqlConfig} instance. 148 */ 149 SqlConfig config() default @SqlConfig; 150 151 152 /** 153 * Enumeration of <em>phases</em> that dictate when SQL scripts are executed. 154 */ 155 enum ExecutionPhase { 156 157 /** 158 * The configured SQL scripts and statements will be executed 159 * <em>before</em> the corresponding test method. 160 */ 161 BEFORE_TEST_METHOD, 162 163 /** 164 * The configured SQL scripts and statements will be executed 165 * <em>after</em> the corresponding test method. 166 */ 167 AFTER_TEST_METHOD 168 } 169 170}