1 /*
2 * Copyright 2009-2024 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.apache.ibatis.annotations;
17
18 import java.lang.annotation.Documented;
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Repeatable;
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.RetentionPolicy;
23 import java.lang.annotation.Target;
24
25 /**
26 * The annotation that specify an SQL for retrieving record(s).
27 * <p>
28 * <b>How to use:</b>
29 * <ul>
30 * <li>Simple:
31 *
32 * <pre>{@code
33 * public interface UserMapper {
34 * @Select("SELECT id, name FROM users WHERE id = #{id}")
35 * User selectById(int id);
36 * }
37 * }</pre>
38 *
39 * </li>
40 * <li>Dynamic SQL:
41 *
42 * <pre>{@code
43 * public interface UserMapper {
44 * @Select({ "<script>", "select * from users", "where name = #{name}",
45 * "<if test=\"age != null\"> age = #{age} </if>", "</script>" })
46 * User select(@NotNull String name, @Nullable Integer age);
47 * }
48 * }</pre>
49 *
50 * </li>
51 * </ul>
52 *
53 * @author Clinton Begin
54 *
55 * @see <a href="https://mybatis.org/mybatis-3/dynamic-sql.html">How to use Dynamic SQL</a>
56 */
57 @Documented
58 @Retention(RetentionPolicy.RUNTIME)
59 @Target(ElementType.METHOD)
60 @Repeatable(Select.List.class)
61 public @interface Select {
62 /**
63 * Returns an SQL for retrieving record(s).
64 *
65 * @return an SQL for retrieving record(s)
66 */
67 String[] value();
68
69 /**
70 * @return A database id that correspond this statement
71 *
72 * @since 3.5.5
73 */
74 String databaseId() default "";
75
76 /**
77 * Returns whether this select affects DB data.<br>
78 * e.g. RETURNING of PostgreSQL or OUTPUT of MS SQL Server.
79 *
80 * @return {@code true} if this select affects DB data; {@code false} if otherwise
81 *
82 * @since 3.5.12
83 */
84 boolean affectData() default false;
85
86 /**
87 * The container annotation for {@link Select}.
88 *
89 * @author Kazuki Shimizu
90 *
91 * @since 3.5.5
92 */
93 @Documented
94 @Retention(RetentionPolicy.RUNTIME)
95 @Target(ElementType.METHOD)
96 @interface List {
97 Select[] value();
98 }
99
100 }