安装包 io.realm

类 RealmObject

  • 所有已实现的接口：
    io.realm.internal.ManageableObject, RealmModel
    直接已知子类：
    DynamicRealmObject
    public abstract class RealmObject
extends Object
implements RealmModel, io.realm.internal.ManageableObject
    在 Realm 中，您可以通过子类化 RealmObject 并添加要持久化的字段来定义 RealmObject 类。 然后，您在 Realm 中创建对象，并使用自定义子类，而不是直接使用 RealmObject 类。

    注解处理器将为您的 RealmObject 子类创建一个代理类。

    支持以下字段数据类型：

    • boolean/Boolean
    • 短/短
    • int/Integer
    • long/Long
    • float/Float
    • double/Double
    • 字节[]
    • 字符串
    • Date
    • UUID
    • org.bson.types.Decimal128
    • org.bson.types.ObjectId
    • 任何 RealmObject 子类
    • RealmList
    • RealmDictionary

    当存储在 Realm 中时，类型short 、 int和long会映射到long 。

    RealmObject 的唯一限制是字段不能为 final 或 易失性。 允许使用任何方法和公共字段。 提供自定义构造函数时，必须声明一个不带参数的公共构造函数。

    用Ignore注解的字段没有这些限制，也不需要 getter 或 setter。

    Realm 将为带有Index注释的字段创建索引。 这会加快查询速度，但会对插入和更新产生负面影响。

    RealmObject 不能在不同线程之间传递。

    另请参阅：
    Realm.createObject(Class), Realm.copyToRealm(RealmModel, ImportFlag...)

    • 构造函数详细信息

      • RealmObject

        public RealmObject()

    • 方法详细信息

      • deleteFromRealm

        public final void deleteFromRealm()
        从当前关联的 Realm 中删除对象。

        调用此方法后，该对象将无效，对其执行的任何操作（读取或写入）都将失败，并抛出IllegalStateException。

        抛出异常：
        IllegalStateException - 如果相应的 Realm 已关闭或位于不正确的线程中。
        另请参阅：
        isValid()

      • deleteFromRealm

        public static <E extends RealmModel> void deleteFromRealm​(E object)
        从当前关联的 Realm 中删除对象。

        调用此方法后，该对象将无效，对其执行的任何操作（读取或写入）都将失败，并抛出IllegalStateException。

        抛出异常：
        IllegalStateException - 如果相应的 Realm 已关闭或位于不正确的线程中。
        另请参阅：
        isValid()

      • isValid

        public final boolean isValid()
        检查 RealmObject 是否仍可有效使用，即 RealmObject 未被删除， Realm未被关闭。 对于非托管对象，它将始终返回true 。

        请注意，这可用于检查某些条件的有效性，例如在满足条件时是否为null 。 

         
 realm.where(BannerRealm.class).equalTo("type", type).findFirstAsync().asFlowable()
      .filter(result.isLoaded() && result.isValid())
      .first()
        指定者：
        isValid 在接口中 io.realm.internal.ManageableObject
        返回：
        true 如果该对象仍可访问或是为非托管对象，则为false 。
        另请参阅：
        将 Realm 与 RxJava 结合使用的示例

      • isValid

        public static <E extends RealmModel> boolean isValid​(@Nullable
                                                     E object)
        检查 RealmObject 是否仍可有效使用，即 RealmObject 未被删除， Realm未被关闭。 对于非托管对象，它将始终返回true 。
        参数：
        object — 要检查其有效性的 RealmObject。
        返回：
        true 如果该对象仍可访问或是为非托管对象，则为false 。

      • IsFrozen

        public final boolean isFrozen()
        返回此 RealmObject 是否被冻结。
        指定者：
        isFrozen 在接口中 io.realm.internal.ManageableObject
        返回：
        true 如果 RealmObject 已冻结，否则为false 。
        另请参阅：
        freeze()

      • 冻结

        public final <E extends RealmModel> E freeze()
        返回此对象的冻结快照。可以从任何线程读取和查询冻结的副本，而不会引发IllegalStateException 。

        冻结 RealmObject 还会创建一个具有自己的生命周期的冻结 Realm，但如果生成原始collection的活动 Realm 完全关闭（即 所有线程上的所有实例均已关闭），冻结的 Realm 和对象也将关闭。

        可以像平常一样查询冻结对象，但尝试以任何方式对其进行更改或尝试注册侦听器都会抛出IllegalStateException 。

        注意：让大量不同版本的冻结对象保持活动状态可能会对 Realm 的文件大小产生负面影响。 为了避免这种情况，可以设置RealmConfiguration.Builder.maxNumberOfActiveVersions(long) 。

        返回：
        此对象的冻结副本。
        抛出异常：
        IllegalStateException - 如果从写事务（write transaction）内部调用此方法。

      • IsFrozen

        public static <E extends RealmModel> boolean isFrozen​(E object)
        返回此 RealmObject 是否被冻结。
        返回：
        true 如果 RealmObject 已冻结，否则为false 。
        另请参阅：
        freeze()

      • 冻结

        public static <E extends RealmModel> E freeze​(E object)
        返回此对象的冻结快照。可以从任何线程读取和查询冻结的副本，而不会引发IllegalStateException 。

        冻结 RealmObject 还会创建一个具有自己的生命周期的冻结 Realm，但如果生成原始collection的活动 Realm 完全关闭（即 所有线程上的所有实例均已关闭），冻结的 Realm 和对象也将关闭。

        可以像平常一样查询冻结对象，但尝试以任何方式对其进行更改或尝试注册侦听器都会抛出IllegalStateException 。

        注意：让大量不同版本的冻结对象保持活动状态可能会对 Realm 的文件大小产生负面影响。 为了避免这种情况，可以设置RealmConfiguration.Builder.maxNumberOfActiveVersions(long) 。

        返回：
        此对象的冻结副本。
        抛出异常：
        IllegalStateException - 如果从写事务（write transaction）内部调用此方法。

      • isLoaded

        public final boolean isLoaded()
        检查用于查找此 RealmObject 的查询是否已完成。

        RealmQuery.findFirstAsync()等异步方法会返回RealmObject ，表示RealmQuery的未来结果。 在这方面，可以认为它与Future类似。

        一旦isLoaded()返回true ，即使查询未找到与查询参数匹配的任何对象，该对象也会表示查询结果。 在这种情况下， RealmObject将成为“空”对象。

        “Null”对象表示null 。 调用任何访问器都会引发异常，因此在调用任何方法之前检查isValid()非常重要。 一种常见的模式是： 

         
 Person person = realm.where(Person.class).findFirstAsync();
 person.isLoaded(); // == false
 person.addChangeListener(new RealmChangeListener() {
      \@Override
      public void onChange(Person person) {
          person.isLoaded(); // Always true here
          if (person.isValid()) {
              // It is safe to access the person.
          }
      }
 });

        根据定义，同步 RealmObject 是阻塞的，因此此方法将始终为其返回true 。 如果对非托管对象（在 Realm 外部创建）调用，此方法将返回true 。

        返回：
        true 如果查询已完成，则如果查询正在进行，则为false 。
        另请参阅：
        isValid()

      • isLoaded

        public static <E extends RealmModel> boolean isLoaded​(E object)
        检查用于查找此 RealmObject 的查询是否已完成。

        RealmQuery.findFirstAsync()等异步方法会返回RealmObject ，表示RealmQuery的未来结果。 在这方面，可以认为它与Future类似。

        一旦isLoaded()返回true ，即使查询未找到与查询参数匹配的任何对象，该对象也会表示查询结果。 在这种情况下， RealmObject将成为“空”对象。

        “Null”对象表示null 。 调用任何访问器都会引发异常，因此在调用任何方法之前检查isValid()非常重要。 一种常见的模式是： 

         
 Person person = realm.where(Person.class).findFirstAsync();
 RealmObject.isLoaded(person); // == false
 RealmObject.addChangeListener(person, new RealmChangeListener() {
      \@Override
      public void onChange(Person person) {
          RealmObject.isLoaded(person); // always true here
          if (RealmObject.isValid(person)) {
              // It is safe to access the person.
          }
      }
 });

        根据定义，同步 RealmObject 是阻塞的，因此此方法将始终为其返回true 。 如果对非托管对象（在 Realm 外部创建）调用，此方法将返回true 。

        参数：
        object - 要检查的 RealmObject。
        返回：
        true 如果查询已完成，则如果查询正在进行，则为false 。
        另请参阅：
        isValid(RealmModel)

      • isManaged

        public boolean isManaged()
        检查此对象是否由 Realm 托管。 托管对象只是底层 Realm 文件中数据的包装器。 在 事件循环 线程上，托管对象将实时更新，因此它始终指向最新数据。可以使用addChangeListener(RealmChangeListener)注册变更监听器，以便在发生更改时收到通知。 托管对象具有线程限制，因此除了创建它们的线程之外，其他线程无法访问它们。

        如果此方法返回false ，则该对象为非托管对象。 非托管对象只是一个普通的 Java 对象，因此可以跨线程自由解析，但对象中的数据未连接到底层 Realm，因此不会实时更新。

        可以使用Realm.copyToRealm(RealmModel, ImportFlag...)从非托管对象创建托管对象。 可以使用Realm.copyFromRealm(RealmModel)从托管对象创建非托管对象。

        指定者：
        isManaged 在接口中 io.realm.internal.ManageableObject
        返回：
        true 如果对象为托管对象，则为false ，如果为非托管对象。

      • isManaged

        public static <E extends RealmModel> boolean isManaged​(E object)
        检查此对象是否由 Realm 托管。 托管对象只是底层 Realm 文件中数据的包装器。 在 事件循环 线程上，托管对象将实时更新，因此它始终指向最新数据。可以使用addChangeListener(RealmModel, RealmChangeListener)注册变更监听器，以便在发生更改时收到通知。 托管对象具有线程限制，因此除了创建它们的线程之外，其他线程无法访问它们。

        如果此方法返回false ，则该对象为非托管对象。 非托管对象只是一个普通的 Java 对象，因此可以跨线程自由解析，但对象中的数据未连接到底层 Realm，因此不会实时更新。

        可以使用Realm.copyToRealm(RealmModel, ImportFlag...)从非托管对象创建托管对象。 可以使用Realm.copyFromRealm(RealmModel)从托管对象创建非托管对象。

        返回：
        true 如果对象为托管对象，则为false ，如果为非托管对象。

      • 负载

        public final boolean load()
        使异步查询阻塞。 这也将trigger所有已注册的侦听器。

        注意：如果针对非托管对象（在 Realm 外部创建）调用，将返回true 。

        返回：
        true 如果成功完成查询，则为false 。

      • 负载

        public static <E extends RealmModel> boolean load​(E object)
        使异步查询阻塞。 这也将trigger所有已注册的侦听器。

        注意：如果针对非托管对象（在 Realm 外部创建）调用，将返回true 。

        参数：
        object - 用于强制加载的 RealmObject。
        返回：
        true 如果成功完成查询，则为false 。

      • addChangeListener

        public final <E extends RealmModel> void addChangeListener​(RealmObjectChangeListener<E> listener)
        向此 RealmObject 添加变更侦听器，以获取有关变更的详细信息。 如果任何值字段或引用的 RealmObject 字段发生更改，或者 RealmList 字段本身发生更改，则会触发监听器。

        注册变更侦听器不会阻止底层 RealmObject 被垃圾收集。 如果对 RealmObject 进行垃圾回收，则将停止触发变更侦听器。 为避免这种情况，请尽可能长时间地保留强引用，例如在类变量中。 

         
 public class MyActivity extends Activity {

     private Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmObjectChangeListener<Person>() {
           \@Override
           public void onChange(Person person, ObjectChangeSet changeSet) {
               // React to change
           }
       });
     }
 }
        参数：
        listener - 要通知的变更侦听器。
        抛出异常：
        IllegalArgumentException - 如果变更侦听器为null或对象为非托管对象。
        IllegalStateException - 如果您尝试从非 事件循环 或IntentService线程添加侦听器。
        IllegalStateException - 如果您尝试在事务中添加侦听器。

      • addChangeListener

        public final <E extends RealmModel> void addChangeListener​(RealmChangeListener<E> listener)
        在此 RealmObject 中添加一个变更侦听器，如果任何值字段或引用的 RealmObject 字段发生更改，或者 RealmList 字段本身发生更改，则会触发该变更侦听器。

        注册变更侦听器不会阻止底层 RealmObject 被垃圾收集。 如果对 RealmObject 进行垃圾回收，则将停止触发变更侦听器。 为避免这种情况，请尽可能长时间地保留强引用，例如在类变量中。 

         
 public class MyActivity extends Activity {

     private Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmChangeListener<Person>() {
           \@Override
           public void onChange(Person person) {
               // React to change
           }
       });
     }
 }
        参数：
        listener - 要通知的变更侦听器。
        抛出异常：
        IllegalArgumentException - 如果变更侦听器为null或对象为非托管对象。
        IllegalStateException - 如果您尝试从非 事件循环 或IntentService线程添加侦听器。
        IllegalStateException - 如果您尝试在事务中添加侦听器。

      • addChangeListener

        public static <E extends RealmModel> void addChangeListener​(E object,
                                                            RealmObjectChangeListener<E> listener)
        向 RealmObject 添加变更侦听器以获取有关变更的详细信息。 如果任何值字段或引用的 RealmObject 字段发生更改，或者 RealmList 字段本身发生更改，则会触发监听器。

        注册变更侦听器不会阻止底层 RealmObject 被垃圾收集。 如果对 RealmObject 进行垃圾回收，则将停止触发变更侦听器。 为避免这种情况，请尽可能长时间地保留强引用，例如在类变量中。 

         
 public class MyActivity extends Activity {

     private Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmObjectChangeListener<Person>() {
           \@Override
           public void onChange(Person person, ObjectChangeSet changeSet) {
               // React to change
           }
       });
     }
 }
        参数：
        object — 要向其添加侦听器的 RealmObject。
        listener - 要通知的变更侦听器。
        抛出异常：
        IllegalArgumentException - 如果object为null或非托管对象，或者变更侦听器为null 。
        IllegalStateException - 如果您尝试从非 事件循环 或IntentService线程添加侦听器。
        IllegalStateException - 如果您尝试在事务中添加侦听器。

      • addChangeListener

        public static <E extends RealmModel> void addChangeListener​(E object,
                                                            RealmChangeListener<E> listener)
        向 RealmObject 添加变更侦听器，如果任何值字段或引用的 RealmObject 字段发生更改，或者 RealmList 字段本身发生更改，则会触发该变更侦听器。

        注册变更侦听器不会阻止底层 RealmObject 被垃圾收集。 如果对 RealmObject 进行垃圾回收，则将停止触发变更侦听器。 为避免这种情况，请尽可能长时间地保留强引用，例如在类变量中。 

         
 public class MyActivity extends Activity {

     private Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmChangeListener<Person>() {
           \@Override
           public void onChange(Person person) {
               // React to change
           }
       });
     }
 }
        参数：
        object — 要向其添加侦听器的 RealmObject。
        listener - 要通知的变更侦听器。
        抛出异常：
        IllegalArgumentException - 如果object为null或非托管对象，或者变更侦听器为null 。
        IllegalStateException - 如果您尝试从非 事件循环 或IntentService线程添加侦听器。
        IllegalStateException - 如果您尝试在事务中添加侦听器。

      • removeChangeListener

        public final void removeChangeListener​(RealmObjectChangeListener listener)
        删除以前注册的侦听器。
        参数：
        listener - 要删除的实例。
        抛出异常：
        IllegalArgumentException - 如果变更侦听器为null或对象为非托管对象。
        IllegalStateException - 如果尝试从非 事件循环 线程中删除侦听器。

      • removeChangeListener

        public final void removeChangeListener​(RealmChangeListener listener)
        删除以前注册的侦听器。
        参数：
        listener - 要删除的实例。
        抛出异常：
        IllegalArgumentException - 如果变更侦听器为null或对象为非托管对象。
        IllegalStateException - 如果尝试从非 事件循环 线程中删除侦听器。

      • removeChangeListener

        public static <E extends RealmModel> void removeChangeListener​(E object,
                                                               RealmObjectChangeListener listener)
        删除先前在给定 RealmObject 上注册的侦听器。
        参数：
        object - 要从中删除侦听器的 RealmObject。
        listener - 要删除的实例。
        抛出异常：
        IllegalArgumentException - 如果object或变更侦听器为null 。
        IllegalArgumentException - 如果对象是非托管 RealmObject。
        IllegalStateException - 如果尝试从非 事件循环 线程中删除侦听器。

      • removeChangeListener

        public static <E extends RealmModel> void removeChangeListener​(E object,
                                                               RealmChangeListener<E> listener)
        删除先前在给定 RealmObject 上注册的侦听器。
        参数：
        object - 要从中删除侦听器的 RealmObject。
        listener - 要删除的实例。
        抛出异常：
        IllegalArgumentException - 如果object或变更侦听器为null 。
        IllegalArgumentException - 如果对象是非托管 RealmObject。
        IllegalStateException - 如果尝试从非 事件循环 线程中删除侦听器。

      • 删除所有变更监听器

        public final void removeAllChangeListeners()
        删除所有已注册的侦听器。

      • 删除所有变更监听器

        public static <E extends RealmModel> void removeAllChangeListeners​(E object)
        从给定 RealmObject 中删除所有已注册的侦听器。
        参数：
        object - 要从中删除所有侦听器的 RealmObject。
        抛出异常：
        IllegalArgumentException - 如果对象为null或不受 Realm 托管。

      • asFlowable

        public final <E extends RealmObject> Flowable<E> asFlowable()
        返回一个监控此 RealmObject 变更的 RxJava Flowable。 订阅时，它将发出当前对象。 更新 RealmObject 时将不断发出对象更新 — 永远不会调用onComplete 。

        链接 RealmObject flowable 时，请使用obj.<MyRealmObjectClass>asFlowable()传递类型信息，否则以下可观察量的类型将为RealmObject 。

        从 Realm Flowable 发出的项被冻结（请参阅freeze() 。 这意味着它们是不可变的，可以在任何线程上读取。

        Realm Flowables 始终从持有活动 Realm 的线程中发出项目。 这意味着，如果需要进行进一步处理，建议观察计算调度器上的值：

        obj.asFlowable() .observeOn(Schedulers.computation()) .map((rxObj) -> doExpensiveWork(rxObj)) .observeOn(AndroidSchedulers.mainThread()) .subscribe( ... );

        如果希望asFlowable()停止发出项目，可以使用first()操作符指示 RxJava 仅发出第一项： 

         
 obj.asFlowable()
      .filter(obj -> obj.isLoaded())
      .first()
      .subscribe( ... ) // You only get the object once

        类型参数：
        E - 正在观察的 RealmObject 类。 必须是此类或其超类型。
        返回：
        仅调用onNext的 RxJava Observable。 它永远不会调用onComplete或OnError 。
        抛出异常：
        UnsupportedOperationException - 如果所需的 RxJava 框架不在类路径上，或者相应的 Realm 实例不支持 RxJava。
        IllegalStateException - 如果 Realm 不是在 事件循环 线程上打开的。
        另请参阅：
        RxJava 和 Realm

      • asChangesetObservable

        public final <E extends RealmObject> Observable<ObjectChange<E>> asChangesetObservable()
        返回一个 Rx Observable，用于监控此 RealmObject 的变更。 订阅时，它将发出当前 RealmObject。 对于 RealmObject 的每次更新，都将发送由 RealmObject 和ObjectChangeSet组成的对。 首次发出 RealmObject 时，变更集将为null 。

        RealmObject 在更新时会不断发出 - onComplete将永远不会被调用。

        从 Realm Observables 发出的项被冻结（请参阅freeze() 。 这意味着它们是不可变的，可以在任何线程上读取。

        Realm Observables 始终从持有活动 Realm 的线程中发出项目。 这意味着，如果需要进行进一步处理，建议观察计算调度器上的值：

        obj.asChangesetObservable() .observeOn(Schedulers.computation()) .map((rxObj, changes) -> doExpensiveWork(rxObj, changeså)) .observeOn(AndroidSchedulers.mainThread()) .subscribe( ... );

        返回：
        仅调用onNext的 RxJava Observable。 它永远不会调用onComplete或OnError 。
        抛出异常：
        UnsupportedOperationException - 如果所需的 RxJava 框架不在类路径上，或者相应的 Realm 实例不支持 RxJava。
        IllegalStateException - 如果 Realm 不是在 事件循环 线程上打开的。
        另请参阅：
        RxJava 和 Realm

      • asFlowable

        public static <E extends RealmModel> Flowable<E> asFlowable​(E object)
        返回一个监控此 RealmObject 变更的 RxJava Flowable。 订阅时，它将发出当前对象。 更新 RealmObject 时将不断发出对象更新 — 永远不会调用onComplete 。

        链接 RealmObject 可观察量时，请使用obj.<MyRealmObjectClass>asFlowable()传递类型信息，否则以下可观察量的类型将为RealmObject 。

        从 Realm Flowable 发出的项被冻结（请参阅freeze() 。 这意味着它们是不可变的，可以在任何线程上读取。

        Realm Flowables 始终从持有活动 Realm 的线程中发出项目。 这意味着，如果需要进行进一步处理，建议观察计算调度器上的值：

        obj.asFlowable() .observeOn(Schedulers.computation()) .map((rxObj) -> doExpensiveWork(rxObj)) .observeOn(AndroidSchedulers.mainThread()) .subscribe( ... );

        如果希望asFlowable()停止发出项目，可以使用first()操作符指示 RxJava 仅发出第一项： 

         
 obj.asFlowable()
      .filter(obj -> obj.isLoaded())
      .first()
      .subscribe( ... ) // You only get the object once
        参数：
        object - 正在观察的 RealmObject 类。 必须是此类或其超类型。
        返回：
        仅调用onNext的 RxJava Observable。 它永远不会调用onComplete或OnError 。
        抛出异常：
        UnsupportedOperationException - 如果所需的 RxJava 框架不在类路径中。
        IllegalStateException - 如果 Realm 不是在 事件循环 线程上打开的。
        另请参阅：
        RxJava 和 Realm

      • asChangesetObservable

        public static <E extends RealmModel> Observable<ObjectChange<E>> asChangesetObservable​(E object)
        返回一个 Rx Observable，用于监控此 RealmObject 的变更。 订阅时，它将发出当前 RealmObject。 对于 RealmObject 的每次更新，都将发送由 RealmObject 和ObjectChangeSet组成的对。 首次发出 RealmObject 时，变更集将为null 。

        RealmObject 在更新时会不断发出 - onComplete将永远不会被调用。

        从 Realm Observables 发出的项被冻结（请参阅freeze() 。 这意味着它们是不可变的，可以在任何线程上读取。

        Realm Observables 始终从持有活动 Realm 的线程中发出项目。 这意味着，如果需要进行进一步处理，建议观察计算调度器上的值：

        obj.asChangesetObservable() .observeOn(Schedulers.computation()) .map((rxObj, changes) -> doExpensiveWork(rxObj, changeså)) .observeOn(AndroidSchedulers.mainThread()) .subscribe( ... );

        参数：
        object - 正在观察的 RealmObject 类。 必须是此类或其超类型。
        返回：
        仅调用onNext的 RxJava Observable。 它永远不会调用onComplete或OnError 。
        抛出异常：
        UnsupportedOperationException - 如果所需的 RxJava 框架不在类路径上，或者相应的 Realm 实例不支持 RxJava。
        IllegalStateException - 如果 Realm 不是在 事件循环 线程上打开的。
        另请参阅：
        RxJava 和 Realm