room/room-common/src/main/java/androidx/room/Relation.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

import kotlin.reflect.KClass

/**
 * A convenience annotation which can be used in a POJO to automatically fetch relation entities.
 * When the POJO is returned from a query, all of its relations are also fetched by Room.
 *
 * ```
 * @Entity
 * data class Song (
 *     @PrimaryKey
 *     val songId: Int,
 *     val albumId: Int,
 *     val name: String
 *     // other fields
 * )
 *
 * data class AlbumNameAndAllSongs (
 *     val id: Int,
 *     val name: String,
 *     @Relation(parentColumn = "id", entityColumn = "albumId")
 *     val songs: List<Song>
 * )
 *
 * @Dao
 * public interface MusicDao {
 *     @Query("SELECT id, name FROM Album")
 *     fun loadAlbumAndSongs(): List<AlbumNameAndAllSongs>
 * }
 * ```
 *
 * For a one-to-many or many-to-many relationship, the type of the field annotated with
 * `Relation` must be a [java.util.List] or [java.util.Set].
 *
 * By default, the [Entity] type is inferred from the return type.
 * If you would like to return a different object, you can specify the [entity] property
 * in the annotation.
 *
 * ```
 * data class Album (
 *     val id: Int
 *     // other fields
 * )
 *
 * data class SongNameAndId (
 *     val songId: Int,
 *     val name: String
 * )
 *
 * data class AlbumAllSongs (
 *     @Embedded
 *     val album: Album,
 *     @Relation(parentColumn = "id", entityColumn = "albumId", entity = Song.class)
 *     val songs: List<SongNameAndId>
 * )
 *
 * @Dao
 * public interface MusicDao {
 *     @Query("SELECT * from Album")
 *     val loadAlbumAndSongs(): List<AlbumAllSongs>
 * }
 * ```
 *
 * In the example above, `SongNameAndId` is a regular POJO but all of fields are fetched
 * from the `entity` defined in the `@Relation` annotation _Song_.
 * `SongNameAndId` could also define its own relations all of which would also be fetched
 * automatically.
 *
 * If you would like to specify which columns are fetched from the child [Entity], you can
 * use [projection] property in the `Relation` annotation.
 *
 * ```
 * data class AlbumAndAllSongs (
 *     @Embedded
 *     val album: Album,
 *     @Relation(
 *         parentColumn = "id",
 *         entityColumn = "albumId",
 *         entity = Song.class,
 *         projection = {"name"})
 *     val songNames: List<String>
 * )
 * ```
 *
 * If the relationship is defined by an associative table (also know as junction table) then you can
 * use [associateBy] to specify it. This is useful for fetching many-to-many relations.
 *
 * Note that `@Relation` annotation can be used only in POJO classes, an [Entity] class
 * cannot have relations. This is a design decision to avoid common pitfalls in [Entity]
 * setups. You can read more about it in the main
 * [Room documentation](https://developer.android.com/training/data-storage/room/referencing-data#understand-no-object-references).
 * When loading data, you can simply work around this limitation by creating
 * POJO classes that extend the [Entity].
 *
 * @see [Junction]
 */
@Target(AnnotationTarget.FIELD, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.BINARY)
public annotation class Relation(
    /**
     * The entity or view to fetch the item from. You don't need to set this if the entity or view
     * matches the type argument in the return type.
     *
     * @return The entity or view to fetch from. By default, inherited from the return type.
     */
    val entity: KClass<*> = Any::class,

    /**
     * Reference column in the parent POJO.
     *
     * In a one-to-one or one-to-many relation, this value will be matched against the column
     * defined in [entityColumn]. In a many-to-many using [associateBy] then
     * this value will be matched against the [Junction.parentColumn]
     *
     * @return The column reference in the parent object.
     */
    val parentColumn: String,

    /**
     * The column to match in the [entity].
     *
     * In a one-to-one or one-to-many relation, this value will be matched against the column
     * defined in [parentColumn]. In a many-to-many using [associateBy] then
     * this value will be matched against the [Junction.entityColumn].
     */
    val entityColumn: String,

    /**
     * The entity or view to be used as a associative table (also known as a junction table) when
     * fetching the relating entities.
     *
     * @return The junction describing the associative table. By default, no junction is specified
     * and none will be used.
     *
     * @see Junction
     */
    val associateBy: Junction = Junction(Any::class),

    /**
     * If sub columns should be fetched from the entity, you can specify them using this field.
     *
     * By default, inferred from the the return type.
     *
     * @return The list of columns to be selected from the [entity].
     */
    val projection: Array<String> = []
)