1 /*
2  * Copyright (C) 2017 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 /**
20  * Marks a field of an [Entity] or POJO to allow nested fields (i.e. fields of the annotated field's
21  * class) to be referenced directly in the SQL queries.
22  *
23  * If the container is an [Entity], these sub fields will be columns in the [Entity]'s database
24  * table.
25  *
26  * For example, if you have 2 classes:
27  * ```
28  * data class Coordinates (
29  *   val latitude: Double,
30  *   val longitude: Double
31  * )
32  *
33  * data class Address (
34  *   val street: String,
35  *   @Embedded
36  *   val coordinates: Coordinates
37  * )
38  * ```
39  *
40  * Room will consider `latitude` and `longitude` as if they are fields of the `Address` class when
41  * mapping an SQLite row to `Address`.
42  *
43  * So if you have a query that returns `street, latitude, longitude`, Room will properly construct
44  * an `Address` class.
45  *
46  * If the `Address` class is annotated with [Entity], its database table will have 3 columns:
47  * `street`, `latitude` and `longitude`.
48  *
49  * If there is a name conflict with the fields of the sub object and the owner object, you can
50  * specify a [prefix] for the fields of the sub object. Note that prefix is always applied to sub
51  * fields even if they have a [ColumnInfo] with a specific `name`.
52  *
53  * If sub fields of an embedded field has [PrimaryKey] annotation, they **will not** be considered
54  * as primary keys in the owner [Entity].
55  *
56  * When an embedded field is read, if all fields of the embedded field (and its sub fields) are
57  * `null` in the [android.database.Cursor], it is set to `null`. Otherwise, it is constructed.
58  *
59  * Note that even if you have [TypeConverter]s that convert a `null` column into a `non-null` value,
60  * if all columns of the embedded field in the [android.database.Cursor] are null, the
61  * [TypeConverter] will never be called and the embedded field will not be constructed.
62  *
63  * You can override this behavior by annotating the embedded field with
64  * [androidx.annotation.NonNull].
65  */
66 @Target(AnnotationTarget.FIELD, AnnotationTarget.FUNCTION)
67 @Retention(AnnotationRetention.BINARY)
68 public annotation class Embedded(
69     /**
70      * Specifies a prefix to prepend the column names of the fields in the embedded fields.
71      *
72      * For the example above, if we've written:
73      * ```
74      * @Embedded(prefix = "loc_")
75      * val coordinates: Coordinates
76      * ```
77      *
78      * The column names for `latitude` and `longitude` will be `loc_latitude` and `loc_longitude`
79      * respectively.
80      *
81      * By default, prefix is the empty string.
82      *
83      * @return The prefix to be used for the fields of the embedded item.
84      */
85     val prefix: String = ""
86 )
87