room/room-common/src/main/java/androidx/room/Embedded.kt

/*
 * Copyright (C) 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.room

/**
 * Marks a field of an [Entity] or POJO to allow nested fields (i.e. fields of the annotated
 * field's class) to be referenced directly in the SQL queries.
 *
 * If the container is an [Entity], these sub fields will be columns in the [Entity]'s
 * database table.
 *
 * For example, if you have 2 classes:
 *
 * ```
 * data class Coordinates (
 *   val latitude: Double,
 *   val longitude: Double
 * )
 *
 * data class Address (
 *   val street: String,
 *   @Embedded
 *   val coordinates: Coordinates
 * )
 * ```
 *
 * Room will consider `latitude` and `longitude` as if they are fields of the
 * `Address` class when mapping an SQLite row to `Address`.
 *
 * So if you have a query that returns `street, latitude, longitude`, Room will properly
 * construct an `Address` class.
 *
 * If the `Address` class is annotated with [Entity], its database table will have 3
 * columns: `street`, `latitude` and `longitude`.
 *
 * If there is a name conflict with the fields of the sub object and the owner object, you can
 * specify a [prefix] for the fields of the sub object. Note that prefix is always applied
 * to sub fields even if they have a [ColumnInfo] with a specific `name`.
 *
 * If sub fields of an embedded field has [PrimaryKey] annotation, they **will not** be
 * considered as primary keys in the owner [Entity].
 *
 * When an embedded field is read, if all fields of the embedded field (and its sub fields) are
 * `null` in the [android.database.Cursor], it is set to `null`. Otherwise,
 * it is constructed.
 *
 * Note that even if you have [TypeConverter]s that convert a `null` column into a
 * `non-null` value, if all columns of the embedded field in the
 * [android.database.Cursor] are null, the [TypeConverter] will never be called
 * and the embedded field will not be constructed.
 *
 * You can override this behavior by annotating the embedded field with
 * [androidx.annotation.NonNull].
 */
@Target(AnnotationTarget.FIELD, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.BINARY)
public annotation class Embedded(
    /**
     * Specifies a prefix to prepend the column names of the fields in the embedded fields.
     *
     * For the example above, if we've written:
     *
     * ```
     * @Embedded(prefix = "loc_")
     * val coordinates: Coordinates
     * ```
     *
     * The column names for `latitude` and `longitude` will be `loc_latitude` and
     * `loc_longitude` respectively.
     *
     * By default, prefix is the empty string.
     *
     * @return The prefix to be used for the fields of the embedded item.
     */
    val prefix: String = ""
)