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 
17 package androidx.room
18 
19 import androidx.annotation.IntDef
20 import androidx.annotation.RequiresApi
21 
22 /**
23  * Allows specific customization about the column associated with this property.
24  *
25  * For example, you can specify a column name for the property or change the column's type affinity.
26  */
27 @Target(AnnotationTarget.FIELD, AnnotationTarget.FUNCTION)
28 @Retention(AnnotationRetention.BINARY)
29 public annotation class ColumnInfo(
30     /**
31      * Name of the column in the database. Defaults to the property name if not set.
32      *
33      * @return Name of the column in the database.
34      */
35     val name: String = INHERIT_FIELD_NAME,
36 
37     /**
38      * The type affinity for the column, which will be used when constructing the database.
39      *
40      * If it is not specified, the value defaults to [UNDEFINED] and Room resolves it based on the
41      * property's type and available TypeConverters.
42      *
43      * See [SQLite types documentation](https://www.sqlite.org/datatype3.html) for details.
44      *
45      * @return The type affinity of the column. This is either [UNDEFINED], [TEXT], [INTEGER],
46      *   [REAL], or [BLOB].
47      */
48     @Suppress("unused") @get:SQLiteTypeAffinity val typeAffinity: Int = UNDEFINED,
49 
50     /**
51      * Convenience method to index the property.
52      *
53      * If you would like to create a composite index instead, see: [Index].
54      *
55      * @return True if this property should be indexed, false otherwise. Defaults to false.
56      */
57     val index: Boolean = false,
58 
59     /**
60      * The collation sequence for the column, which will be used when constructing the database.
61      *
62      * The default value is [UNSPECIFIED]. In that case, Room does not add any collation sequence to
63      * the column, and SQLite treats it like [BINARY].
64      *
65      * @return The collation sequence of the column. This is either [UNSPECIFIED], [BINARY],
66      *   [NOCASE], [RTRIM], [LOCALIZED] or [UNICODE].
67      */
68     @get:Collate val collate: Int = UNSPECIFIED,
69 
70     /**
71      * The default value for this column.
72      *
73      * ```
74      * @ColumnInfo(defaultValue = "No name")
75      * public name: String
76      *
77      * @ColumnInfo(defaultValue = "0")
78      * public flag: Int
79      * ```
80      *
81      * Note that the default value you specify here will _NOT_ be used if you simply insert the
82      * [Entity] with [Insert]. In that case, any value assigned in Java/Kotlin will be used. Use
83      * [Query] with an `INSERT` statement and skip this column there in order to use this default
84      * value.
85      *
86      * NULL, CURRENT_TIMESTAMP and other SQLite constant values are interpreted as such. If you want
87      * to use them as strings for some reason, surround them with single-quotes.
88      *
89      * ```
90      * @ColumnInfo(defaultValue = "NULL")
91      * public description: String?
92      *
93      * @ColumnInfo(defaultValue = "'NULL'")
94      * public name: String
95      * ```
96      *
97      * You can also use constant expressions by surrounding them with parentheses.
98      *
99      * ```
100      * @ColumnInfo(defaultValue = "('Created at' || CURRENT_TIMESTAMP)")
101      * public notice: String
102      * ```
103      *
104      * @return The default value for this column.
105      * @see [VALUE_UNSPECIFIED]
106      */
107     val defaultValue: String = VALUE_UNSPECIFIED,
108 ) {
109     /** The SQLite column type constants that can be used in [typeAffinity()] */
110     @IntDef(UNDEFINED, TEXT, INTEGER, REAL, BLOB)
111     @Retention(AnnotationRetention.BINARY)
112     public annotation class SQLiteTypeAffinity
113 
114     @RequiresApi(21)
115     @IntDef(UNSPECIFIED, BINARY, NOCASE, RTRIM, LOCALIZED, UNICODE)
116     @Retention(AnnotationRetention.BINARY)
117     public annotation class Collate
118 
119     public companion object {
120         /**
121          * Constant to let Room inherit the property name as the column name. If used, Room will use
122          * the property name as the column name.
123          */
124         public const val INHERIT_FIELD_NAME: String = "[field-name]"
125 
126         /**
127          * Undefined type affinity. Will be resolved based on the type.
128          *
129          * @see typeAffinity()
130          */
131         public const val UNDEFINED: Int = 1
132 
133         /**
134          * Column affinity constant for strings.
135          *
136          * @see typeAffinity()
137          */
138         public const val TEXT: Int = 2
139 
140         /**
141          * Column affinity constant for integers or booleans.
142          *
143          * @see typeAffinity()
144          */
145         public const val INTEGER: Int = 3
146 
147         /**
148          * Column affinity constant for floats or doubles.
149          *
150          * @see typeAffinity()
151          */
152         public const val REAL: Int = 4
153 
154         /**
155          * Column affinity constant for binary data.
156          *
157          * @see typeAffinity()
158          */
159         public const val BLOB: Int = 5
160 
161         /**
162          * Collation sequence is not specified. The match will behave like [BINARY].
163          *
164          * @see collate()
165          */
166         public const val UNSPECIFIED: Int = 1
167 
168         /**
169          * Collation sequence for case-sensitive match.
170          *
171          * @see collate()
172          */
173         public const val BINARY: Int = 2
174 
175         /**
176          * Collation sequence for case-insensitive match.
177          *
178          * @see collate()
179          */
180         public const val NOCASE: Int = 3
181 
182         /**
183          * Collation sequence for case-sensitive match except that trailing space characters are
184          * ignored.
185          *
186          * @see collate()
187          */
188         public const val RTRIM: Int = 4
189 
190         /**
191          * Collation sequence that uses system's current locale.
192          *
193          * @see collate()
194          */
195         @RequiresApi(21) public const val LOCALIZED: Int = 5
196 
197         /**
198          * Collation sequence that uses Unicode Collation Algorithm.
199          *
200          * @see collate()
201          */
202         @RequiresApi(21) public const val UNICODE: Int = 6
203 
204         /** A constant for [defaultValue()] that makes the column to have no default value. */
205         public const val VALUE_UNSPECIFIED: String = "[value-unspecified]"
206     }
207 }
208