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