类 DynamicRealm
- java.lang.Object
-
- io.realm.DynamicRealm
-
- 所有已实现的接口:
Closeable
,AutoCloseable
public class DynamicRealm extends Object
DynamicRealm 是Realm
的动态变体。 这意味着对数据和/或查询的所有访问都是使用基于字符串的类名称而不是类类型引用来完成的。这在迁移期间或处理基于字符串的数据(例如 CSV 或 XML 文件)时非常有用。
相同的
RealmConfiguration
可用于在动态和类型化模式下打开 Realm 文件,但在同时打开类型化和动态版本的情况下修改模式是非常不鼓励的,因为这种操作很可能导致类型化 Realm 崩溃。 在迁移期间,只有一个 DynamicRealm 会打开。动态 Realm 不实施模式或模式版本,也不会使用
RealmMigration
代码,即使它已在RealmConfiguration
中定义。也就是说,在类型化模式下打开 Realm 之前,不会创建或验证模式。 如果首先以动态模式打开 Realm 文件,则该文件将不包含有关类和字段的任何信息,并且对模式定义的类的任何查询都将失败。
- 另请参阅:
Realm
,RealmSchema
-
-
嵌套类摘要
嵌套类 修饰符和类型 类 说明 static class
DynamicRealm.Callback
static interface
DynamicRealm.Transaction
封装 Realm 事务。
-
字段摘要
字段 修饰符和类型 字段 说明 static io.realm.BaseRealm.ThreadLocalRealmObjectContext
objectContext
io.realm.internal.OsSharedRealm
sharedRealm
static io.realm.internal.async.RealmThreadPoolExecutor
WRITE_EXECUTOR
用于写入操作的线程池执行程序 — 由于写入无法并行化,因此仅需要一个线程。
-
方法摘要
所有方法 静态方法 实例方法 具体方法 已弃用的方法 修饰符和类型 方法 说明 void
addChangeListener(RealmChangeListener<DynamicRealm> listener)
为 Realm 添加变更监听器。Flowable<DynamicRealm>
asFlowable()
返回一个监控此 Realm 变更的 RxJava Flowable。void
beginTransaction()
启动必须由BaseRealm.commitTransaction()
关闭或由BaseRealm.cancelTransaction()
中止的事务。void
cancelTransaction()
恢复在当前写事务(write transaction)中进行的所有写入(创建、更新或删除的对象)并结束事务。void
close()
关闭 Realm 实例及其所有资源。void
commitTransaction()
自BaseRealm.beginTransaction()
以来的所有更改都会持久保存到磁盘,并且 Realm 恢复为只读。DynamicRealmObject
createEmbeddedObject(String className, DynamicRealmObject parentObject, String parentProperty)
实例化一个新的嵌入式对象并将其添加到 Realm 中。DynamicRealmObject
createObject(String className)
实例化一个新对象并将其添加到 Realm 中。DynamicRealmObject
createObject(String className, Object primaryKeyValue)
使用给定主键创建对象。void
delete(String className)
从 Realm 中删除指定类的所有对象。void
deleteAll()
删除此 Realm 中的所有对象。void
executeTransaction(DynamicRealm.Transaction transaction)
在 DynamicRealm 上执行给定事务。RealmAsyncTask
executeTransactionAsync(DynamicRealm.Transaction transaction)
与executeTransaction(Transaction)
类似,但在工作线程上异步运行。RealmAsyncTask
executeTransactionAsync(DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnError onError)
与executeTransactionAsync(Transaction)
类似,但也接受 OnError 回调。RealmAsyncTask
executeTransactionAsync(DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnSuccess onSuccess)
与executeTransactionAsync(Transaction)
类似,但也接受 OnSuccess 回调。RealmAsyncTask
executeTransactionAsync(DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnSuccess onSuccess, DynamicRealm.Transaction.OnError onError)
与executeTransactionAsync(Transaction)
类似,但也接受 OnSuccess 和 OnError 回调。DynamicRealm
freeze()
返回当前 Realm 的冻结快照。RealmConfiguration
getConfiguration()
返回此 Realm 的RealmConfiguration
。static DynamicRealm
getInstance(RealmConfiguration configuration)
Realm 静态构造函数,返回由提供的RealmConfiguration
定义的 Realm 实例的动态变体。static RealmAsyncTask
getInstanceAsync(RealmConfiguration configuration, DynamicRealm.Callback callback)
在进程中为每个RealmConfiguration
创建第一个 Realm 实例可能需要一些时间,因为此时所有初始化代码都需要运行(设置 Realm、验证模式和创建初始数据)。long
getNumberOfActiveVersions()
返回此 Realm 当前持有的活动版本的当前数量。String
getPath()
返回此 Realm 在磁盘上持久保存的规范路径。RealmSchema
getSchema()
返回此 Realm 的可变模式。SubscriptionSet
getSubscriptions()
返回与此 Realm 关联的订阅集。long
getVersion()
返回此 Realm 的模式版本。boolean
isAutoRefresh()
检索 Realm 实例的自动刷新状态。boolean
isClosed()
检查Realm
实例是否已关闭。boolean
isEmpty()
检查此Realm
是否包含任何对象。boolean
isFrozen()
返回此 Realm 是否被冻结。boolean
isInTransaction()
检查 Realm 当前是否处于事务中。void
refresh()
刷新 Realm 实例以及来自该实例的所有 RealmResults 和 RealmObjects 实例。void
removeAllChangeListeners()
删除所有用户定义的变更侦听器。void
removeChangeListener(RealmChangeListener<DynamicRealm> listener)
删除指定的变更侦听器。void
setAutoRefresh(boolean autoRefresh)
设置 Realm 实例的自动刷新状态。void
stopWaitForChange()
已弃用。该方法将在下一个主要版本中删除boolean
waitForChange()
已弃用。此方法将在下一个主要版本中删除。RealmQuery<DynamicRealmObject>
where(String className)
返回一个 RealmQuery,可用于查询提供的类。void
writeCopyTo(File destination)
将 Realm 的压缩副本写入给定的目标文件。void
writeEncryptedCopyTo(File destination, byte[] key)
将 Realm 的压缩和加密副本写入给定的目标文件。
-
-
-
字段详细信息
-
WRITE_EXECUTOR
public static final io.realm.internal.async.RealmThreadPoolExecutor WRITE_EXECUTOR
用于写入操作的线程池执行程序 — 由于写入无法并行化,因此仅需要一个线程。
-
SharedRealm
public io.realm.internal.OsSharedRealm sharedRealm
-
objectContext
public static final io.realm.BaseRealm.ThreadLocalRealmObjectContext objectContext
-
-
方法详细信息
-
getInstance
public static DynamicRealm getInstance(RealmConfiguration configuration)
Realm 静态构造函数,返回由提供的RealmConfiguration
定义的 Realm 实例的动态变体。 动态 Realms 不关心 schemaVersion 和模式,因此打开 DynamicRealm 永远不会 trigger 迁移。- 返回:
- 配置定义的 DynamicRealm。
- 抛出异常:
RealmFileException
- 如果在访问底层 Realm 文件时发生错误。IllegalArgumentException
- 如果configuration
参数为null
。- 另请参阅:
for details on how to configure a Realm.
-
getInstanceAsync
public static RealmAsyncTask getInstanceAsync(RealmConfiguration configuration, DynamicRealm.Callback callback)
在进程中为每个RealmConfiguration
创建第一个 Realm 实例可能需要一些时间,因为此时所有初始化代码都需要运行(设置 Realm、验证模式和创建初始数据)。 此方法将初始化工作放在背景线程中,并在初始化完成后将 Realm 实例异步传递给调用者线程。- 参数:
configuration
- 用于打开 Realm 的RealmConfiguration
。callback
— 调用以返回结果。- 返回:
- 表示可取消任务的
RealmAsyncTask
。 - 抛出异常:
IllegalArgumentException
- 如果提供了 nullRealmConfiguration
或 nullDynamicRealm.Callback
。IllegalStateException
- 如果是从非 事件循环 或IntentService
线程调用的。- 另请参阅:
for more details.
-
createObject
public DynamicRealmObject createObject( String className)
实例化一个新对象并将其添加到 Realm 中。- 参数:
className
- 要创建的对象的类名。- 返回:
- 新对象。
- 抛出异常:
RealmException
- 如果无法创建对象。
-
createObject
public DynamicRealmObject createObject( String className, 对象 primaryKeyValue )
使用给定主键创建对象。 未定义主键的类必须使用createObject(String)
} 代替。- 返回:
- 新对象。 所有字段都将具有其类型的默认值,但主键字段除外,它将具有提供的值。
- 抛出异常:
RealmException
- 如果由于主键无效而无法创建对象。IllegalStateException
- 如果模型 clazz 没有定义主键。IllegalArgumentException
- 如果primaryKeyValue
没有可以转换为预期值的值。
-
createEmbeddedObject
public DynamicRealmObject createEmbeddedObject( String className, DynamicRealmObjectparentObject , StringparentProperty )
实例化一个新的嵌入式对象并将其添加到 Realm 中。此方法只应用于创建标记为嵌入式的类型的对象。
- 参数:
className
- 要创建的对象的类名。parentObject
- 应包含对嵌入式对象的引用的父对象。 如果父属性是列表,则嵌入式对象将被添加到该列表的末尾。parentProperty
- 父类中保存引用的属性。- 返回:
- 新创建的嵌入式对象。
- 抛出异常:
IllegalArgumentException
- 如果clazz
不是嵌入式类,或者父类中的属性无法保存适当类型的对象。- 另请参阅:
RealmClass.embedded()
-
WHERE
public RealmQuery<DynamicRealmObject> where(String className)
返回一个 RealmQuery,可用于查询提供的类。- 参数:
className
- 要查询的对象的类。- 返回:
- RealmQuery,可用于查询所提供类型的特定对象。
- 抛出异常:
IllegalArgumentException
- 如果该类不存在。- 另请参阅:
RealmQuery
-
addChangeListener
public void addChangeListener(RealmChangeListener<DynamicRealm> listener)
为 Realm 添加变更监听器。当此线程或另一个线程提交更改时,将执行侦听器。
Realm 实例按线程进行缓存。 因此,请务必记住使用
removeChangeListener(RealmChangeListener)
或removeAllChangeListeners()
再次删除侦听器。 否则可能会导致内存泄漏。- 参数:
listener
— 变更侦听器。- 抛出异常:
IllegalArgumentException
- 如果变更侦听器为null
。- 另请参阅:
RealmChangeListener
、removeChangeListener(RealmChangeListener)
、removeAllChangeListeners()
、refresh()
-
removeChangeListener
public void removeChangeListener(RealmChangeListener<DynamicRealm> listener)
删除指定的变更侦听器。- 参数:
listener
- 要删除的变更侦听器。- 抛出异常:
IllegalArgumentException
- 如果变更侦听器为null
。IllegalStateException
- 如果尝试从非 事件循环 线程中删除侦听器。- 另请参阅:
RealmChangeListener
-
删除所有变更监听器
public void removeAllChangeListeners()
删除所有用户定义的变更侦听器。- 抛出异常:
IllegalStateException
- 如果您尝试从非事件循环线程中删除侦听器。- 另请参阅:
RealmChangeListener
-
删除
public void delete(String className)
从 Realm 中删除指定类的所有对象。- 参数:
className
- 应删除所有对象的类。- 抛出异常:
IllegalStateException
- 如果 Realm 已关闭或从不正确的线程调用。
-
executeTransaction
public void executeTransaction(DynamicRealm.Transaction transaction)
在 DynamicRealm 上执行给定事务。beginTransaction()
和commitTransaction()
将被自动调用。 如果在事务期间引发任何异常,则将调用cancelTransaction()
而不是commitTransaction()
。从用户界面线程调用此方法会抛出
RealmException
。 这样做可能会导致丢帧甚至 ANR。 我们建议从非用户界面线程中调用此方法或改用executeTransactionAsync(Transaction)
。- 参数:
transaction
-DynamicRealm.Transaction
执行。- 抛出异常:
IllegalArgumentException
- 如果transaction
为null
。RealmException
- 如果从用户界面线程调用,除非在RealmConfiguration.Builder.allowWritesOnUiThread(boolean)
中声明了显式选择加入。
-
executeTransactionAsync
public RealmAsyncTaskexecuteTransactionAsync ( DynamicRealm.事务 事务)
与executeTransaction(Transaction)
类似,但在工作线程上异步运行。- 参数:
transaction
-DynamicRealm.Transaction
执行。- 返回:
- 表示可取消任务的
RealmAsyncTask
。 - 抛出异常:
IllegalArgumentException
- 如果transaction
为null
,或者 Realm 是从另一个线程打开的。
-
executeTransactionAsync
public RealmAsyncTaskexecuteTransactionAsync ( DynamicRealm.事务 事务, DynamicRealm.事务.OnSuccess onSuccess)
与executeTransactionAsync(Transaction)
类似,但也接受 OnSuccess 回调。- 参数:
transaction
-DynamicRealm.Transaction
执行。onSuccess
— 事务成功时调用的回调。- 返回:
- 表示可取消任务的
RealmAsyncTask
。 - 抛出异常:
IllegalArgumentException
- 如果transaction
为null
,或者该 Realm 是从另一个线程打开的。
-
executeTransactionAsync
public RealmAsyncTaskexecuteTransactionAsync ( DynamicRealm.事务 事务, DynamicRealm.事务.OnError onError)
与executeTransactionAsync(Transaction)
类似,但也接受 OnError 回调。- 参数:
transaction
-DynamicRealm.Transaction
执行。onError
— 事务失败时调用的回调。- 返回:
- 表示可取消任务的
RealmAsyncTask
。 - 抛出异常:
IllegalArgumentException
- 如果transaction
为null
,或者该 Realm 是从另一个线程打开的。
-
executeTransactionAsync
public RealmAsyncTaskexecuteTransactionAsync ( DynamicRealm.事务 事务, @Nullable DynamicRealm.事务.OnSuccess onSuccess, @Nullable DynamicRealm.事务.OnError onError)
与executeTransactionAsync(Transaction)
类似,但也接受 OnSuccess 和 OnError 回调。- 参数:
transaction
-DynamicRealm.Transaction
执行。onSuccess
— 事务成功时调用的回调。onError
— 事务失败时调用的回调。- 返回:
- 表示可取消任务的
RealmAsyncTask
。 - 抛出异常:
IllegalArgumentException
- 如果transaction
为null
,或者该 Realm 是从另一个线程打开的。
-
asFlowable
public Flowable<DynamicRealm> asFlowable()
返回一个监控此 Realm 变更的 RxJava Flowable。 订阅时,它将发出当前状态。 随着 Realm 更新,项目将不断发出 -onComplete
将永远不会被调用。从 Realm Flowable 发出的项被冻结(请参阅
freeze()
。 这意味着它们是不可变的,可以在任何线程上读取。Realm Flowables 始终从持有活动 Realm 的线程中发出项目。 这意味着,如果需要进行进一步处理,建议观察计算调度器上的值:
realm.asFlowable() .observeOn(Schedulers.computation()) .map(rxRealm -> doExpensiveWork(rxRealm)) .observeOn(AndroidSchedulers.mainThread()) .subscribe( ... );
如果希望
asFlowable()
停止发出项目,可以使用first()
操作符指示 RxJava 仅发出第一项:realm.asFlowable().first().subscribe( ... ); // You only get the results once
- 返回:
- 仅调用
onNext
的 RxJava Observable。 它永远不会调用onComplete
或OnError
。 - 另请参阅:
- RxJava 和 Realm
-
isEmpty
public boolean isEmpty()
检查此Realm
是否包含任何对象。- 返回:
true
如果为空,则为 @{code false} 否则。
-
getSchema
public RealmSchema getSchema()
返回此 Realm 的可变模式。- 返回:
- 此 Realm 的
RealmSchema
。
-
冻结
公共DynamicRealm冻结()
返回当前 Realm 的冻结快照。可以从任何线程读取和查询此 Realm,而不会抛出IllegalStateException
。 冻结的 Realm 有自己的生命周期,可以通过调用Closeable.close()
来关闭,但完全关闭生成冻结副本的 Realm 也会关闭冻结的 Realm。可以正常查询冻结数据,但尝试以任何方式更改数据或尝试注册任何侦听器都会抛出
IllegalStateException
。注意:保持大量不同版本的 Realm 活动可能会对 Realm 的文件大小产生负面影响。 为了避免这种情况,可以设置
RealmConfiguration.Builder.maxNumberOfActiveVersions(long)
。- 返回:
- 此 Realm 的冻结副本。
-
setAutoRefresh
public void setAutoRefresh(boolean autoRefresh)
设置 Realm 实例的自动刷新状态。自动刷新功能可以在对另一个线程中作用于同一文件的 Realm 上执行提交时自动更新当前 Realm 实例及其所有派生对象(RealmResults 和 RealmObject 实例)。 仅当 Realm 实例位于启用了
Looper
的线程上时,此功能才可用。- 参数:
autoRefresh
-true
将打开自动刷新,false
将关闭自动刷新。- 抛出异常:
IllegalStateException
- 如果从非 Looper 线程调用。
-
isAutoRefresh
public boolean isAutoRefresh()
检索 Realm 实例的自动刷新状态。- 返回:
- 自动刷新状态。
-
刷新
public void refresh()
刷新 Realm 实例以及来自该实例的所有 RealmResults 和 RealmObjects 实例。 如果需要,它还会调用与 Realm 关联的任何侦听器。警告:在具有异步查询的线程上调用此函数会将这些查询转换为同步查询。 这意味着,如果将
RealmException
RealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
与true
一起使用来获取 Realm 实例,则该方法将抛出 。在大多数情况下,最好使用RealmChangeListener
来接收给定线程上 Realm 变更的通知,而不是使用此方法。- 抛出异常:
IllegalStateException
- 如果尝试从事务中刷新。RealmException
- 如果通过RealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
选择退出后从用户界面线程调用。
-
isInTransaction
public boolean isInTransaction()
检查 Realm 当前是否处于事务中。- 返回:
true
如果在事务中,则为false
,否则为 。
-
writeCopyTo
public void writeCopyTo(File destination)
将 Realm 的压缩副本写入给定的目标文件。 生成的文件可用作初始数据集,以在其他设备中引导本地或同步的 Realm。目标文件不能是已经存在的文件。
请注意,如果这是从事务内部调用的,则它会写入当前数据,而不是提交最后一个事务时的数据。
- 参数:
destination
- 要保存 Realm 的文件。- 抛出异常:
IllegalArgumentException
- 如果目标参数为 null。RealmFileException
- 如果在访问底层 Realm 文件或写入目标文件时发生错误。IllegalStateException
- 如果从用户界面线程调用。IllegalStateException
- 如果并非所有客户端更改都集成在服务器中。
-
writeEncryptedCopyTo
public void writeEncryptedCopyTo(File destination, byte[] key)
将 Realm 的压缩和加密副本写入给定的目标文件。 生成的文件可用作初始数据集,以在其他设备中引导本地或同步的 Realm。目标文件不能是已经存在的文件。
请注意,如果这是从事务内部调用的,则它会写入当前数据,而不是提交最后一个事务时的数据。
- 参数:
destination
- 要保存 Realm 的文件。key
- 64 字节加密密钥。- 抛出异常:
IllegalArgumentException
- 如果目标参数为 null。RealmFileException
- 如果在访问底层 Realm 文件或写入目标文件时发生错误。IllegalStateException
- 如果从用户界面线程调用。IllegalStateException
- 如果并非所有客户端更改都集成在服务器中。
-
waitForChange
@Deprecated public boolean waitForChange()
已弃用。此方法将在下一个主要版本中删除。阻塞当前线程,直到 Realm 有新的更改可用或从另一个线程调用stopWaitForChange()
。 调用 stopWaitForChange 后,以后对此方法的所有调用都将立即返回 false。- 返回:
true
如果 Realm 已更新到最新版本,则false
如果通过调用 stopWaitForChange 取消。- 抛出异常:
IllegalStateException
- 如果从事务中或 Looper 线程中调用此方法。RealmMigrationNeededException
- 如果最新版本包含不兼容的模式更改,则在键入Realm
时执行。
-
stopWaitForChange
@Deprecated public void stopWaitForChange()
已弃用。该方法将在下一个主要版本中删除使任何当前的waitForChange()
立即返回false
。 调用此方法后,以后对 waitForChange 的所有调用都将立即返回false
。此方法具有线程安全性,_只能_从调用 waitForChange 的线程以外的其他线程调用。
- 抛出异常:
IllegalStateException
- 如果Realm
实例已关闭。
-
beginTransaction
public void beginTransaction()
启动必须由BaseRealm.commitTransaction()
关闭或由BaseRealm.cancelTransaction()
中止的事务。 事务用于以原子方式创建、更新和删除 Realm 中的对象。在开始事务之前,Realm 实例会更新到最新版本,以包含其他线程的所有更改。 此更新不会触发任何已注册的
RealmChangeListener
。因此,建议从事务内部查询应修改的项目。 否则,在事务开始时,可能存在部分结果被删除或修改的风险。
// Don't do this RealmResults<Person> persons = realm.where(Person.class).findAll(); realm.beginTransaction(); persons.first().setName("John"); realm.commitTransaction(); // Do this instead realm.beginTransaction(); RealmResults<Person> persons = realm.where(Person.class).findAll(); persons.first().setName("John"); realm.commitTransaction();
注意:无法嵌套事务。 如果在事务中启动事务,则会引发异常。
- 抛出异常:
RealmMigrationNeededException
- 如果最新版本包含不兼容的模式更改,则在键入Realm
时执行。
-
commitTransaction
public void commitTransaction()
自BaseRealm.beginTransaction()
以来的所有更改都会持久保存到磁盘,并且 Realm 恢复为只读。 系统会发送一个事件,通知所有其他 Realm 实例已发生更改。 收到该事件后,其他 Realm 将更新其对象和RealmResults
以反映本次提交的更改。
-
cancelTransaction
public void cancelTransaction()
恢复在当前写事务(write transaction)中进行的所有写入(创建、更新或删除的对象)并结束事务。Realm 将恢复为只读。
不在事务中时调用此方法会引发异常。
-
IsFrozen
public boolean isFrozen()
返回此 Realm 是否被冻结。- 返回:
true
如果 Realm 已冻结,则为false
,否则为 。- 另请参阅:
freeze()
-
getNumberOfActiveVersions
public long getNumberOfActiveVersions()
返回此 Realm 当前持有的活动版本的当前数量。拥有大量的活动版本会对 Realm 文件的大小产生负面影响。 请参阅常见问题解答以了解更多信息。
- 返回:
- Realm 当前持有的活动版本数。
- 另请参阅:
RealmConfiguration.Builder.maxNumberOfActiveVersions(long)
-
getPath
public String getPath()
返回此 Realm 在磁盘上持久保存的规范路径。- 返回:
- Realm 文件的规范路径。
- 另请参阅:
File.getCanonicalPath()
-
getConfiguration
public RealmConfiguration getConfiguration()
返回此 Realm 的RealmConfiguration
。- 返回:
- 此 Realm 的
RealmConfiguration
。
-
getVersion
public long getVersion()
返回此 Realm 的模式版本。- 返回:
- 支持此 Realm 的 Realm 文件的模式版本。
-
关闭
public void close()
关闭 Realm 实例及其所有资源。请务必记住在使用完 Realm 实例后关闭 Realm 实例,以免泄漏内存、文件描述符或 Realm 文件大小增长不正常。
- 指定者:
close
在接口中AutoCloseable
- 指定者:
close
在接口中Closeable
- 抛出异常:
IllegalStateException
- 如果尝试从另一个线程关闭。
-
isClosed
public boolean isClosed()
检查Realm
实例是否已关闭。- 返回:
true
如果已关闭,则为false
。- 抛出异常:
IllegalStateException
- 如果尝试从另一个线程关闭。
-
getSubscriptions
public SubscriptionSet getSubscriptions()
返回与此 Realm 关联的订阅集。 订阅集定义了一组查询,这些查询定义了在此域和服务器之间同步哪些数据。此方法仅适用于使用 Flexible Sync 的同步 Realm。
- 返回:
- 与此 Realm 关联的订阅集。
- 抛出异常:
IllegalStateException
- 如果此 Realm 是本地 Realm 或基于分区的同步 Realm。
-
deleteAll
public void deleteAll()
删除此 Realm 中的所有对象。- 抛出异常:
IllegalStateException
- 如果 Realm 已关闭或从不正确的线程调用。
-
-