1/*
2 * Copyright (C) 2016 The Android Open Source Project
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 *      http://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
17package android.arch.persistence.room;
18
19import android.support.annotation.IntDef;
20
21import java.lang.annotation.ElementType;
22import java.lang.annotation.Retention;
23import java.lang.annotation.RetentionPolicy;
24import java.lang.annotation.Target;
25
26/**
27 * Allows specific customization about the column associated with this field.
28 * <p>
29 * For example, you can specify a column name for the field or change the column's type affinity.
30 */
31@Target(ElementType.FIELD)
32@Retention(RetentionPolicy.CLASS)
33public @interface ColumnInfo {
34    /**
35     * Name of the column in the database. Defaults to the field name if not set.
36     *
37     * @return Name of the column in the database.
38     */
39    String name() default INHERIT_FIELD_NAME;
40
41    /**
42     * The type affinity for the column, which will be used when constructing the database.
43     * <p>
44     * If it is not specified, the value defaults to {@link #UNDEFINED} and Room resolves it based
45     * on the field's type and available TypeConverters.
46     * <p>
47     * See <a href="https://www.sqlite.org/datatype3.html">SQLite types documentation</a> for
48     * details.
49     *
50     * @return The type affinity of the column. This is either {@link #UNDEFINED}, {@link #TEXT},
51     * {@link #INTEGER}, {@link #REAL}, or {@link #BLOB}.
52     */
53    @SuppressWarnings("unused") @SQLiteTypeAffinity int typeAffinity() default UNDEFINED;
54
55    /**
56     * Convenience method to index the field.
57     * <p>
58     * If you would like to create a composite index instead, see: {@link Index}.
59     *
60     * @return True if this field should be indexed, false otherwise. Defaults to false.
61     */
62    boolean index() default false;
63
64    /**
65     * The collation sequence for the column, which will be used when constructing the database.
66     * <p>
67     * The default value is {@link #UNSPECIFIED}. In that case, Room does not add any
68     * collation sequence to the column, and SQLite treats it like {@link #BINARY}.
69     *
70     * @return The collation sequence of the column. This is either {@link #UNSPECIFIED},
71     * {@link #BINARY}, {@link #NOCASE}, or {@link #RTRIM}.
72     */
73    @Collate int collate() default UNSPECIFIED;
74
75    /**
76     * Constant to let Room inherit the field name as the column name. If used, Room will use the
77     * field name as the column name.
78     */
79    String INHERIT_FIELD_NAME = "[field-name]";
80
81    /**
82     * Undefined type affinity. Will be resolved based on the type.
83     *
84     * @see #typeAffinity()
85     */
86    int UNDEFINED = 1;
87    /**
88     * Column affinity constant for strings.
89     *
90     * @see #typeAffinity()
91     */
92    int TEXT = 2;
93    /**
94     * Column affinity constant for integers or booleans.
95     *
96     * @see #typeAffinity()
97     */
98    int INTEGER = 3;
99    /**
100     * Column affinity constant for floats or doubles.
101     *
102     * @see #typeAffinity()
103     */
104    int REAL = 4;
105    /**
106     * Column affinity constant for binary data.
107     *
108     * @see #typeAffinity()
109     */
110    int BLOB = 5;
111
112    /**
113     * The SQLite column type constants that can be used in {@link #typeAffinity()}
114     */
115    @IntDef({UNDEFINED, TEXT, INTEGER, REAL, BLOB})
116    @interface SQLiteTypeAffinity {
117    }
118
119    /**
120     * Collation sequence is not specified. The match will behave like {@link #BINARY}.
121     *
122     * @see #collate()
123     */
124    int UNSPECIFIED = 1;
125    /**
126     * Collation sequence for case-sensitive match.
127     *
128     * @see #collate()
129     */
130    int BINARY = 2;
131    /**
132     * Collation sequence for case-insensitive match.
133     *
134     * @see #collate()
135     */
136    int NOCASE = 3;
137    /**
138     * Collation sequence for case-sensitive match except that trailing space characters are
139     * ignored.
140     *
141     * @see #collate()
142     */
143    int RTRIM = 4;
144
145    @IntDef({UNSPECIFIED, BINARY, NOCASE, RTRIM})
146    @interface Collate {
147    }
148}
149