room/room-common/src/main/java/androidx/room/ForeignKey.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 androidx.annotation.IntDef
import kotlin.reflect.KClass

/**
 * Declares a foreign key on another [Entity].
 *
 * Foreign keys allows you to specify constraints across Entities such that SQLite will ensure that
 * the relationship is valid when you modify the database.
 *
 * When a foreign key constraint is specified, SQLite requires the referenced columns to be part of
 * a unique index in the parent table or the primary key of that table. You must create a unique
 * index in the parent entity that covers the referenced columns (Room will verify this at compile
 * time and print an error if it is missing).
 *
 * It is also recommended to create an index on the child table to avoid full table scans when the
 * parent table is modified. If a suitable index on the child table is missing, Room will print
 * [RoomWarnings.MISSING_INDEX_ON_FOREIGN_KEY_CHILD] warning.
 *
 * A foreign key constraint can be deferred until the transaction is complete. This is useful if
 * you are doing bulk inserts into the database in a single transaction. By default, foreign key
 * constraints are immediate but you can change this value by setting [deferred] to
 * `true`. You can also use
 * [defer_foreign_keys](https://sqlite.org/pragma.html#pragma_defer_foreign_keys) to defer them
 * depending on your transaction.
 *
 * Please refer to the SQLite [foreign keys](https://sqlite.org/foreignkeys.html) documentation for
 * details.
 */
@Target(allowedTargets = []) // Complex annotation target
@Retention(AnnotationRetention.BINARY)
public annotation class ForeignKey(
    /**
     * The parent Entity to reference. It must be a class annotated with [Entity] and
     * referenced in the same database.
     *
     * @return The parent Entity.
     */
    val entity: KClass<*>,

    /**
     * The list of column names in the parent [Entity].
     *
     * Number of columns must match the number of columns specified in [childColumns].
     *
     * @return The list of column names in the parent Entity.
     * @see [childColumns]
     */
    val parentColumns: Array<String>,

    /**
     * The list of column names in the current [Entity].
     *
     * Number of columns must match the number of columns specified in [parentColumns].
     *
     * @return The list of column names in the current Entity.
     */
    val childColumns: Array<String>,

    /**
     * Action to take when the parent [Entity] is deleted from the database.
     *
     * By default, [NO_ACTION] is used.
     *
     * @return The action to take when the referenced entity is deleted from the database.
     */
    @Action
    val onDelete: Int = NO_ACTION,

    /**
     * Action to take when the parent [Entity] is updated in the database.
     *
     * By default, [NO_ACTION] is used.
     *
     * @return The action to take when the referenced entity is updated in the database.
     */
    @Action
    val onUpdate: Int = NO_ACTION,

    /**
     * A foreign key constraint can be deferred until the transaction is complete. This is useful
     * if you are doing bulk inserts into the database in a single transaction. By default, foreign
     * key constraints are immediate but you can change it by setting this field to `true`.
     * You can also use
     * [defer_foreign_keys](https://sqlite.org/pragma.html#pragma_defer_foreign_keys)
     * PRAGMA to defer them depending on your transaction.
     *
     * @return Whether the foreign key constraint should be deferred until the transaction is
     * complete. Defaults to `false`.
     */
    val deferred: Boolean = false
) {
    public companion object {
        /**
         * Possible value for [onDelete] or [onUpdate].
         *
         * When a parent key is modified or deleted from the database, no special action is taken.
         * This means that SQLite will not make any effort to fix the constraint failure, instead,
         * reject the change.
         */
        public const val NO_ACTION: Int = 1

        /**
         * Possible value for [onDelete] or [onUpdate].
         *
         * The RESTRICT action means that the application is prohibited from deleting
         * (for [onDelete]) or modifying (for [onUpdate]) a parent key when there
         * exists one or more child keys mapped to it. The difference between the effect of a RESTRICT
         * action and normal foreign key constraint enforcement is that the RESTRICT action processing
         * happens as soon as the field is updated - not at the end of the current statement as it would
         * with an immediate constraint, or at the end of the current transaction as it would with a
         * [deferred] constraint.
         *
         * Even if the foreign key constraint it is attached to is [deferred], configuring a
         * RESTRICT action causes SQLite to return an error immediately if a parent key with dependent
         * child keys is deleted or modified.
         */
        public const val RESTRICT: Int = 2

        /**
         * Possible value for [onDelete] or [onUpdate].
         *
         * If the configured action is "SET NULL", then when a parent key is deleted
         * (for [onDelete]) or modified (for [onUpdate]), the child key columns of all
         * rows in the child table that mapped to the parent key are set to contain `NULL` values.
         */
        public const val SET_NULL: Int = 3

        /**
         * Possible value for [onDelete] or [onUpdate].
         *
         * The "SET DEFAULT" actions are similar to [SET_NULL], except that each of the child key
         * columns is set to contain the columns default value instead of `NULL`.
         */
        public const val SET_DEFAULT: Int = 4

        /**
         * Possible value for [onDelete] or [onUpdate].
         *
         * A "CASCADE" action propagates the delete or update operation on the parent key to each
         * dependent child key. For [onDelete] action, this means that each row in the child
         * entity that was associated with the deleted parent row is also deleted. For an
         * [onUpdate] action, it means that the values stored in each dependent child key are
         * modified to match the new parent key values.
         */
        public const val CASCADE: Int = 5
    }

    /**
     * Constants definition for values that can be used in [onDelete] and
     * [onUpdate].
     */
    @IntDef(NO_ACTION, RESTRICT, SET_NULL, SET_DEFAULT, CASCADE)
    @Retention(AnnotationRetention.BINARY)
    public annotation class Action
}