All Downloads are FREE. Search and download functionalities are using the official Maven repository.

commonMain.io.realm.kotlin.dynamic.DynamicRealmObject.kt Maven / Gradle / Ivy

Go to download

Library code for Realm Kotlin. This artifact is not supposed to be consumed directly, but through 'io.realm.kotlin:gradle-plugin:1.11.1' instead.

There is a newer version: 3.0.0
Show newest version
/*
 * Copyright 2022 Realm Inc.
 *
 * 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 io.realm.kotlin.dynamic

import io.realm.kotlin.Realm
import io.realm.kotlin.query.RealmResults
import io.realm.kotlin.schema.RealmStorageType
import io.realm.kotlin.types.BaseRealmObject
import io.realm.kotlin.types.EmbeddedRealmObject
import io.realm.kotlin.types.RealmDictionary
import io.realm.kotlin.types.RealmList
import io.realm.kotlin.types.RealmObject
import io.realm.kotlin.types.RealmSet
import kotlin.reflect.KClass

/**
 * A **dynamic realm object** gives access to the data of the realm objects through a generic string
 * based API instead of the conventional [Realm] API that only allows access through the properties
 * of the corresponding schema classes supplied in the configuration.
 */
public interface DynamicRealmObject : BaseRealmObject {
    /**
     * The type of the object.
     *
     * This will normally correspond to the name of a model class that is extending
     * [RealmObject] or [EmbeddedRealmObject].
     */
    public val type: String

    /**
     * Returns the value of a specific non-nullable value property.
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different value
     * types:
     * ```
     * // Retrieve a nullable int from a 'nullableIntField' property
     * dynamicRealmObject.getNullableValue("nullableIntField", Int::class)
     *
     * // Retrieve a non-nullable int from an 'intField' property
     * dynamicRealmObject.getValue("intField", Int::class)
     *
     * // Retrieve an object from an `objectField' property
     * dynamicRealmObject.getObject("objectField", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the property to retrieve the value for.
     * @param clazz the Kotlin class of the value. Must match the [RealmStorageType.kClass] of the
     *              property in the realm.
     * @param T the type of the value.
     * @return the property value.
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if `clazz` doesn't match the property's [RealmStorageType.kClass] or if trying to
     * retrieve collection properties.
     */
    public fun  getValue(propertyName: String, clazz: KClass): T

    /**
     * Returns the value of a specific nullable value property.
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different value
     * types:
     * ```
     * // Retrieve a nullable int from a 'nullableIntField' property
     * dynamicRealmObject.getNullableValue("nullableIntField", Int::class)
     *
     * // Retrieve a non-nullable int from an 'intField' property
     * dynamicRealmObject.getValue("intField", Int::class)
     *
     * // Retrieve an object from an `objectField' property
     * dynamicRealmObject.getObject("objectField", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the property to retrieve the value for.
     * @param clazz the Kotlin class of the value.
     * @param T the type of the value.
     * @return the [RealmList] value.
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if `clazz` doesn't match the property's [RealmStorageType.kClass] or if trying to
     * retrieve collection properties.
     */
    public fun  getNullableValue(propertyName: String, clazz: KClass): T?

    /**
     * Returns the value of an object property.
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different value
     * types:
     * ```
     * // Retrieve a nullable int from a 'nullableIntField' property
     * dynamicRealmObject.getNullableValue("nullableIntField", Int::class)
     *
     * // Retrieve a non-nullable int from an 'intField' property
     * dynamicRealmObject.getValue("intField", Int::class)
     *
     * // Retrieve an object from an `objectField' property
     * dynamicRealmObject.getObject("objectField", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the property to retrieve the value for.
     * @return the [RealmList] value.
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if `clazz` doesn't match the property's [RealmStorageType.kClass] or if trying to
     * retrieve collection properties.
     */
    public fun getObject(propertyName: String): DynamicRealmObject?

    /**
     * Returns the list of non-nullable value elements referenced by the property name as a
     * [RealmList].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different list
     * types:
     * ```
     * // Retrieve a list of nullable ints from a 'nullableIntList' property
     * dynamicRealmObject.getNullableValueList("nullableIntList", Int::class)
     *
     * // Retrieve a list of non-nullable ints from a 'intList' property
     * dynamicRealmObject.getValueList("intList", Int::class)
     *
     * // Retrieve a list of objects from an `objectList' property
     * // Object lists are ALWAYS non-nullable
     * dynamicRealmObject.getObjectList("objectList", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the list property to retrieve the list for.
     * @param clazz the Kotlin class of the list element type.
     * @param T the type of the list element type.
     * @return the referenced [RealmList]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-list properties or if `clazz` doesn't match the
     * property's [RealmStorageType.kClass].
     */
    public fun  getValueList(propertyName: String, clazz: KClass): RealmList

    /**
     * Returns the list of nullable elements referenced by the property name as a [RealmList].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different list
     * types:
     * ```
     * // Retrieve a list of nullable ints from a 'nullableIntList' property
     * dynamicRealmObject.getNullableValueList("nullableIntList", Int::class)
     *
     * // Retrieve a list of non-nullable ints from a 'intList' property
     * dynamicRealmObject.getValueList("intList", Int::class)
     *
     * // Retrieve a list of objects from an `objectList' property
     * // Object lists are ALWAYS non-nullable
     * dynamicRealmObject.getObjectList("objectList", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the list property to retrieve the list for.
     * @param clazz the Kotlin class of the list element type.
     * @param T the type of the list element type.
     * @return the referenced [RealmList]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-list properties or if `clazz` doesn't match the
     * property's [RealmStorageType.kClass].
     */
    public fun  getNullableValueList(propertyName: String, clazz: KClass): RealmList

    /**
     * Returns the list of objects referenced by the property name as a [RealmList].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different list
     * types:
     * ```
     * // Retrieve a list of nullable ints from a 'nullableIntList' property
     * dynamicRealmObject.getNullableValueList("nullableIntList", Int::class)
     *
     * // Retrieve a list of non-nullable ints from a 'intList' property
     * dynamicRealmObject.getValueList("intList", Int::class)
     *
     * // Retrieve a list of objects from an `objectList' property
     * // Object lists are ALWAYS non-nullable
     * dynamicRealmObject.getObjectList("objectList", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the list property to retrieve the list for.
     * @return the referenced [RealmList]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-list properties or if `clazz` doesn't match the
     * property's [RealmStorageType.kClass].
     */
    public fun getObjectList(propertyName: String): RealmList

    /**
     * Returns the set of non-nullable value elements referenced by the property name as a
     * [RealmSet].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different set types:
     * ```
     * // Retrieve a set of nullable ints from a 'nullableIntSet' property
     * dynamicRealmObject.getNullableValueSet("nullableIntSet", Int::class)
     *
     * // Retrieve a set of non-nullable ints from a 'intSet' property
     * dynamicRealmObject.getValueSet("intSet", Int::class)
     *
     * // Retrieve a set of objects from an `objectSet' property
     * // Object sets are ALWAYS non-nullable
     * dynamicRealmObject.getObjectSet("objectSet", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the set property to retrieve the set for.
     * @param clazz the Kotlin class of the set element type.
     * @param T the type of the set element type.
     * @return the referenced [RealmSet]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-set properties or if `clazz` doesn't match the
     * property's [RealmStorageType.kClass].
     */
    public fun  getValueSet(propertyName: String, clazz: KClass): RealmSet

    /**
     * Returns the set of nullable elements referenced by the property name as a [RealmSet].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different set types:
     * ```
     * // Retrieve a set of nullable ints from a 'nullableIntSet' property
     * dynamicRealmObject.getNullableValueSet("nullableIntSet", Int::class)
     *
     * // Retrieve a set of non-nullable ints from a 'intSet' property
     * dynamicRealmObject.getValueSet("intSet", Int::class)
     *
     * // Retrieve a set of objects from an `objectSet' property
     * // Object sets are ALWAYS non-nullable
     * dynamicRealmObject.getObjectSet("objectSet", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the set property to retrieve the set for.
     * @param clazz the Kotlin class of the set element type.
     * @param T the type of the set element type.
     * @return the referenced [RealmSet]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-set properties or if `clazz` doesn't match the
     * property's [RealmStorageType.kClass].
     */
    public fun  getNullableValueSet(propertyName: String, clazz: KClass): RealmSet

    /**
     * Returns the set of objects referenced by the property name as a [RealmSet].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different set types:
     * ```
     * // Retrieve a set of nullable ints from a 'nullableIntSet' property
     * dynamicRealmObject.getNullableValueSet("nullableIntSet", Int::class)
     *
     * // Retrieve a set of non-nullable ints from a 'intSet' property
     * dynamicRealmObject.getValueSet("intSet", Int::class)
     *
     * // Retrieve a set of objects from an `objectSet' property
     * // Object sets are ALWAYS non-nullable
     * dynamicRealmObject.getObjectSet("objectSet", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the set property to retrieve the set for.
     * @return the referenced [RealmSet]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-set properties or if `clazz` doesn't match the
     * property's [RealmStorageType.kClass].
     */
    public fun getObjectSet(propertyName: String): RealmSet

    /**
     * Returns the dictionary of non-nullable value elements referenced by the property name as a
     * [RealmDictionary].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different dictionary
     * types:
     * ```
     * // Retrieve a dictionary of nullable ints from a 'nullableIntDictionary' property
     * dynamicRealmObject.getNullableValueDictionary("nullableIntDictionary", Int::class)
     *
     * // Retrieve a dictionary of non-nullable ints from a 'intDictionary' property
     * dynamicRealmObject.getValueDictionary("intDictionary", Int::class)
     *
     * // Retrieve a dictionary of objects from an `objectDictionary' property
     * // Object dictionaries are ALWAYS nullable
     * dynamicRealmObject.getObjectDictionary("objectDictionary", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the dictionary property to retrieve the dictionary for.
     * @param clazz the Kotlin class of the dictionary element type.
     * @param T the type of the dictionary element type.
     * @return the referenced [RealmDictionary]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-dictionary properties or if `clazz` doesn't match
     * the property's [RealmStorageType.kClass].
     */
    public fun  getValueDictionary(
        propertyName: String,
        clazz: KClass
    ): RealmDictionary

    /**
     * Returns the dictionary of nullable elements referenced by the property name as a
     * [RealmDictionary].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different dictionary
     * types:
     * ```
     * // Retrieve a dictionary of nullable ints from a 'nullableIntDictionary' property
     * dynamicRealmObject.getNullableValueDictionary("nullableIntDictionary", Int::class)
     *
     * // Retrieve a dictionary of non-nullable ints from a 'intDictionary' property
     * dynamicRealmObject.getValueDictionary("intDictionary", Int::class)
     *
     * // Retrieve a dictionary of objects from an `objectDictionary' property
     * // Object dictionaries are ALWAYS nullable
     * dynamicRealmObject.getObjectDictionary("objectDictionary", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the dictionary property to retrieve the dictionary for.
     * @param clazz the Kotlin class of the dictionary element type.
     * @param T the type of the dictionary element type.
     * @return the referenced [RealmDictionary]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-dictionary properties or if `clazz` doesn't match
     * the property's [RealmStorageType.kClass].
     */
    public fun  getNullableValueDictionary(
        propertyName: String,
        clazz: KClass
    ): RealmDictionary

    /**
     * Returns the dictionary of objects referenced by the property name as a [RealmDictionary].
     *
     * The `class` argument must be the [KClass] of the [RealmStorageType] for the property.
     *
     * The following snippet outlines the different functions available for the different dictionary
     * types:
     * ```
     * // Retrieve a dictionary of nullable ints from a 'nullableIntDictionary' property
     * dynamicRealmObject.getNullableValueDictionary("nullableIntDictionary", Int::class)
     *
     * // Retrieve a dictionary of non-nullable ints from a 'intDictionary' property
     * dynamicRealmObject.getValueDictionary("intDictionary", Int::class)
     *
     * // Retrieve a dictionary of objects from an `objectDictionary' property
     * // Object dictionaries are ALWAYS nullable
     * dynamicRealmObject.getObjectDictionary("objectDictionary", DynamicRealmObject::class)
     * ```
     *
     * @param propertyName the name of the dictionary property to retrieve the dictionary for.
     * @return the referenced [RealmDictionary]
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non-dictionary properties or if `clazz` doesn't match
     * the property's [RealmStorageType.kClass].
     */
    public fun getObjectDictionary(propertyName: String): RealmDictionary

    /**
     * Returns a backlinks collection referenced by the property name as a [RealmResults].
     *
     * @param propertyName the name of the backlinks property to retrieve for.
     * @return the referencing objects as a [RealmResults].
     * @throws IllegalArgumentException if the class doesn't contain a field with the specific
     * name, if trying to retrieve values for non backlinks properties.
     */
    public fun getBacklinks(propertyName: String): RealmResults
}

/**
 * Returns the value of a specific value property.
 *
 * Reified convenience wrapper of [DynamicRealmObject.getValue].
 */
public inline fun  DynamicRealmObject.getValue(fieldName: String): T =
    this.getValue(fieldName, T::class)

/**
 * Returns the value of a specific nullable value property.
 *
 * Reified convenience wrapper of [DynamicRealmObject.getNullableValue].
 */
public inline fun  DynamicRealmObject.getNullableValue(fieldName: String): T? =
    this.getNullableValue(fieldName, T::class)

/**
 * Returns the list referenced by the property name as a [RealmList].
 *
 * Reified convenience wrapper of [DynamicRealmObject.getValueList].
 */
public inline fun  DynamicRealmObject.getValueList(fieldName: String): RealmList =
    this.getValueList(fieldName, T::class)

/**
 * Returns the list of nullable elements referenced by the property name as a [RealmList].
 *
 * Reified convenience wrapper of [DynamicRealmObject.getNullableValueList].
 */
public inline fun  DynamicRealmObject.getNullableValueList(fieldName: String): RealmList =
    this.getNullableValueList(fieldName, T::class)

/**
 * Returns the set referenced by the property name as a [RealmSet].
 *
 * Reified convenience wrapper of [DynamicRealmObject.getValueSet].
 */
public inline fun  DynamicRealmObject.getValueSet(fieldName: String): RealmSet =
    this.getValueSet(fieldName, T::class)

/**
 * Returns the set of nullable elements referenced by the property name as a [RealmSet].
 *
 * Reified convenience wrapper of [DynamicRealmObject.getNullableValueSet].
 */
public inline fun  DynamicRealmObject.getNullableValueSet(fieldName: String): RealmSet =
    this.getNullableValueSet(fieldName, T::class)

/**
 * Returns the set referenced by the property name as a [RealmDictionary].
 *
 * Reified convenience wrapper of [DynamicRealmObject.getValueSet].
 */
public inline fun  DynamicRealmObject.getValueDictionary(fieldName: String): RealmDictionary =
    this.getValueDictionary(fieldName, T::class)

/**
 * Returns the set of nullable elements referenced by the property name as a [RealmDictionary].
 *
 * Reified convenience wrapper of [DynamicRealmObject.getNullableValueSet].
 */
public inline fun  DynamicRealmObject.getNullableValueDictionary(fieldName: String): RealmDictionary =
    this.getNullableValueDictionary(fieldName, T::class)




© 2015 - 2024 Weber Informatics LLC | Privacy Policy