Monarchy (monarchy 2.0.0 API)

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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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.
`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(int maxDepth, Monarchy.Query<T> query)` Returns a LiveData that evaluates the new results on a background looper thread.
`<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.
`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
  - findAllCopiedWithChanges
```
public <T extends RealmModel> <any> findAllCopiedWithChanges(int maxDepth,
                                                             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, maxDepth)`.
    
    Type Parameters:
    
    T - the RealmModel type
    
    Parameters:
    
    maxDepth - the max depth
    
    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

Class Monarchy

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

init

setDefaultConfiguration

getDefaultConfiguration

getRealmConfiguration

runTransactionSync

doWithRealm

writeAsync

fetchAllManagedSync

fetchAllCopiedSync

fetchAllMappedSync

findAllCopiedWithChanges

findAllCopiedWithChanges

findAllFrozenWithChanges

findAllMappedWithChanges

findAllManagedWithChanges

findAllManagedWithChangesSync

openManually

closeManually

isMonarchyThreadOpen

postToMonarchyThread