com.zhuinden.monarchy

Class Monarchy

java.lang.Object

com.zhuinden.monarchy.Monarchy

public final class Monarchy
extends java.lang.Object

Monarchy is a wrapper around Realm that simplifies its lifecycle management, and leverages the power of LiveData. Not only does it auto-manage the Realm lifecycle, but specifically prevents the ability to use Realm in such a way that it is impossible to leave a Realm instance open by accident. In case of `copied`, `mapped`, or `paged` results, the queries are evaluated on a background looper thread. In case of `managed` results, the RealmResults is provided along with its change set.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Monarchy.Builder Builder class used to build a Monarchy instance.
static class	Monarchy.ManagedChangeSet<T extends RealmModel> A class that contains the RealmResults and the OrderedCollectionChangeSet.
static interface	Monarchy.Mapper<R,T> A mapper interface that can be used in findAllMappedWithChanges(Query, Mapper) to map out instances on the background looper thread.
static interface	Monarchy.Query<T extends RealmModel> An interface used to define Realm queries, therefore bypassing the thread-local aspect of RealmQuery.
static interface	Monarchy.RealmBlock Interface to define what to do with the Realm instance.
static class	Monarchy.RealmDataSourceFactory<T extends RealmModel> A DataSource.Factory that handles integration of RealmResults through Paging.

Method Summary

Modifier and Type	Method and Description
void	closeManually() If the Monarchy thread was opened manually, then this method can be used to decrement the forced reference count increment.
<T extends RealmModel> Monarchy.RealmDataSourceFactory<T>	createDataSourceFactory(Monarchy.Query<T> query) Creates a DataSource.Factory of (Integer, T) that can be used for creating a paged result set.
void	doWithRealm(Monarchy.RealmBlock realmBlock) Allows to manually use Realm instance and will automatically close it when done.
<T extends RealmModel> java.util.List<T>	fetchAllCopiedSync(Monarchy.Query<T> query) Provides ability to synchronously fetch a copied RealmResults.
<T extends RealmModel> java.util.List<T>	fetchAllManagedSync(Realm realm, Monarchy.Query<T> query) Provides ability to synchronously obtain a managed RealmResults as a List, in a safe way.
<T extends RealmModel,U> java.util.List<U>	fetchAllMappedSync(Monarchy.Query<T> query, Monarchy.Mapper<U,T> mapper) Provides ability to synchronously fetch a mapped RealmResults.
<T extends RealmModel> <any>	findAllCopiedWithChanges(Monarchy.Query<T> query) Returns a LiveData that evaluates the new results on a background looper thread.
<T extends RealmModel> <any>	findAllFrozenWithChanges(Monarchy.Query<T> query) Returns a LiveData that evaluates the new results on a background looper thread.
<T extends RealmModel> <any>	findAllManagedWithChanges(Monarchy.Query<T> query) Returns a LiveData that evaluates the new results on the UI thread, using Realm's Async Query API.
<T extends RealmModel> <any>	findAllManagedWithChangesSync(Monarchy.Query<T> query) Returns a LiveData that evaluates the new results on the UI thread, using Realm's Sync Query API.
<T extends RealmModel,U> <any>	findAllMappedWithChanges(Monarchy.Query<T> query, Monarchy.Mapper<U,T> mapper) Returns a LiveData that evaluates the new results on a background looper thread.
<R,T extends RealmModel> <any>	findAllPagedWithChanges(<any> dataSourceFactory, <any> livePagedListBuilder) Returns a LiveData that evaluates the new results on a background looper thread.
static RealmConfiguration	getDefaultConfiguration() Returns the default configuration.
RealmConfiguration	getRealmConfiguration()
static void	init(android.content.Context context) Initializes Realm as usual, except sets a default configuration to detect if a custom default is properly set.
boolean	isMonarchyThreadOpen() Returns if the Monarchy thread is open.
void	openManually() Forcefully opens the Monarchy thread, keeping it alive until closeManually() is called.
void	postToMonarchyThread(Monarchy.RealmBlock realmBlock) Posts the RealmBlock to the Monarchy thread, and executes it there.
void	runTransactionSync(Realm.Transaction transaction)
static void	setDefaultConfiguration(RealmConfiguration realmConfiguration) Calls Realm.setDefaultConfiguration(config).
void	writeAsync(Realm.Transaction transaction) Writes asynchronously on a single-threaded execution pool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

init

public static void init(android.content.Context context)

Initializes Realm as usual, except sets a default configuration to detect if a custom default is properly set.

Parameters:

context - app context

setDefaultConfiguration

public static void setDefaultConfiguration(RealmConfiguration realmConfiguration)

Calls Realm.setDefaultConfiguration(config).

Parameters:

realmConfiguration - realm configuration

getDefaultConfiguration

public static RealmConfiguration getDefaultConfiguration()

Returns the default configuration.

Returns:

the custom default configuration

Throws:

java.lang.IllegalStateException - if the invalid default configuration is still set.

getRealmConfiguration

public final RealmConfiguration getRealmConfiguration()

runTransactionSync

public final void runTransactionSync(Realm.Transaction transaction)

doWithRealm

public final void doWithRealm(Monarchy.RealmBlock realmBlock)

Allows to manually use Realm instance and will automatically close it when done.

Parameters:

realmBlock - the Realm execution block in which Realm should remain open

writeAsync

public final void writeAsync(Realm.Transaction transaction)

Writes asynchronously on a single-threaded execution pool.

Parameters:

transaction - the Realm transaction

fetchAllManagedSync

public <T extends RealmModel> java.util.List<T> fetchAllManagedSync(Realm realm,
                                                                    Monarchy.Query<T> query)

Provides ability to synchronously obtain a managed RealmResults as a List, in a safe way. What is actually returned is a snapshot collection. This method only makes sense either if Realm is opened manually, or inside a doWithRealm(RealmBlock) (or runTransactionSync(Realm.Transaction) method).

Type Parameters:

T - RealmObject type

Parameters:

realm - Realm

query - Query

Returns:

the snapshot collection

fetchAllCopiedSync

public <T extends RealmModel> java.util.List<T> fetchAllCopiedSync(Monarchy.Query<T> query)

Provides ability to synchronously fetch a copied RealmResults.

Type Parameters:

T - RealmObject type

Parameters:

query - Query

Returns:

the copied list

fetchAllMappedSync

public <T extends RealmModel,U> java.util.List<U> fetchAllMappedSync(Monarchy.Query<T> query,
                                                                     Monarchy.Mapper<U,T> mapper)

Provides ability to synchronously fetch a mapped RealmResults.

Type Parameters:

T - RealmObject type

U - the mapped type

Parameters:

query - Query

Returns:

the copied list

findAllCopiedWithChanges

public <T extends RealmModel> <any> findAllCopiedWithChanges(Monarchy.Query<T> query)

Returns a LiveData that evaluates the new results on a background looper thread. The observer receives new data when the database changes. The items are copied out with `realm.copyFromRealm(results)`.

Type Parameters:

T - the RealmModel type

Parameters:

query - the query

Returns:

the LiveData

findAllFrozenWithChanges

public <T extends RealmModel> <any> findAllFrozenWithChanges(Monarchy.Query<T> query)

Returns a LiveData that evaluates the new results on a background looper thread. The observer receives new data when the database changes. The items are frozen with `realmResults.freeze()`.

Type Parameters:

T - the RealmModel type

Parameters:

query - the query

Returns:

the LiveData

findAllMappedWithChanges

public <T extends RealmModel,U> <any> findAllMappedWithChanges(Monarchy.Query<T> query,
                                                               Monarchy.Mapper<U,T> mapper)

Returns a LiveData that evaluates the new results on a background looper thread. The observer receives new data when the database changes. The items are mapped out with the provided Monarchy.Mapper.

Type Parameters:

T - the RealmModel type

U - the mapped type

Parameters:

query - the query

Returns:

the LiveData

findAllManagedWithChanges

public <T extends RealmModel> <any> findAllManagedWithChanges(Monarchy.Query<T> query)

Returns a LiveData that evaluates the new results on the UI thread, using Realm's Async Query API. The observer receives new data when the database changes. The managed change set contains the OrderedCollectionChangeSet evaluated by Realm.

Type Parameters:

T - the RealmModel type

Parameters:

query - the query

Returns:

the LiveData

findAllManagedWithChangesSync

public <T extends RealmModel> <any> findAllManagedWithChangesSync(Monarchy.Query<T> query)

Returns a LiveData that evaluates the new results on the UI thread, using Realm's Sync Query API. The observer receives new data when the database changes. The managed change set contains the OrderedCollectionChangeSet evaluated by Realm.

Type Parameters:

T - the RealmModel type

Parameters:

query - the query

Returns:

the LiveData

openManually

public void openManually()

Forcefully opens the Monarchy thread, keeping it alive until closeManually() is called.

closeManually

public void closeManually()

If the Monarchy thread was opened manually, then this method can be used to decrement the forced reference count increment. This means that the Monarchy thread does not stop unless all observed LiveData are also inactive.

isMonarchyThreadOpen

public boolean isMonarchyThreadOpen()

Returns if the Monarchy thread is open.

Returns:

if the monarchy thread is open

postToMonarchyThread

public void postToMonarchyThread(Monarchy.RealmBlock realmBlock)

Posts the RealmBlock to the Monarchy thread, and executes it there.

Parameters:

realmBlock - the Realm block

Throws:

java.lang.IllegalStateException - if the Monarchy thread is not open

createDataSourceFactory

public <T extends RealmModel> Monarchy.RealmDataSourceFactory<T> createDataSourceFactory(Monarchy.Query<T> query)

Creates a DataSource.Factory of (Integer, T) that can be used for creating a paged result set. By default behavior, the created query is synchronous.

Parameters:

query - the query

findAllPagedWithChanges

public <R,T extends RealmModel> <any> findAllPagedWithChanges(<any> dataSourceFactory,
                                                              <any> livePagedListBuilder)

Returns a LiveData that evaluates the new results on a background looper thread. The resulting list is driven by a PositionalDataSource from the Paging Library. The fetch executor of the provided LivePagedListBuilder will be overridden with Monarchy's own FetchExecutor that Monarchy runs its queries on.