BoxStore (objectbox-java 2.9.1 API)

java.lang.Object
- io.objectbox.BoxStore

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable
```
@ThreadSafe
public class BoxStore
extends java.lang.Object
implements java.io.Closeable
```
An ObjectBox database that provides Boxes to put and get Objects of a specific Entity class (see boxFor(Class)). To get an instance of this class use MyObjectBox.builder().

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String JNI_VERSION
Change so ReLinker will update native library when using workaround loading.

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`JNI_VERSION` Change so ReLinker will update native library when using workaround loading.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`io.objectbox.Transaction`	`beginReadTx()` Internal, low level method: use `runInReadTx(Runnable)` instead.
`io.objectbox.Transaction`	`beginTx()` Internal, low level method: use `runInTx(Runnable)` instead.
`<T> Box<T>`	`boxFor(java.lang.Class<T> entityClass)` Returns a Box for the given type.
`<T> T`	`callInReadTx(java.util.concurrent.Callable<T> callable)` Calls the given callable inside a read(-only) transaction.
`<T> T`	`callInReadTxWithRetry(java.util.concurrent.Callable<T> callable, int attempts, int initialBackOffInMs, boolean logAndHeal)` Calls `callInReadTx(Callable)` and retries in case a DbException is thrown.
`<R> R`	`callInTx(java.util.concurrent.Callable<R> callable)` Like `runInTx(Runnable)`, but allows returning a value and throwing an exception.
`<R> void`	`callInTxAsync(java.util.concurrent.Callable<R> callable, TxCallback<R> callback)` Runs the given Runnable as a transaction in a separate thread.
`<R> R`	`callInTxNoException(java.util.concurrent.Callable<R> callable)` Like `callInTx(Callable)`, but throws no Exception.
`int`	`cleanStaleReadTransactions()`
`static boolean`	`clearDefaultStore()` Clears the convenience instance.
`void`	`close()` Closes the BoxStore and frees associated resources.
`void`	`closeThreadResources()` Call this method from a thread that is about to be shutdown or likely not to use ObjectBox anymore: it frees any cached resources tied to the calling thread (e.g.
`boolean`	`deleteAllFiles()` Danger zone! This will delete all data (files) of this BoxStore! You must call `close()` before and read the docs of that method carefully!
`static boolean`	`deleteAllFiles(java.io.File objectStoreDirectory)` Danger zone! This will delete all files in the given directory!
`static boolean`	`deleteAllFiles(java.io.File baseDirectoryOrNull, java.lang.String customDbNameOrNull)` Danger zone! This will delete all files in the given directory!
`static boolean`	`deleteAllFiles(java.lang.Object androidContext, java.lang.String customDbNameOrNull)` Danger zone! This will delete all files in the given directory!
`java.lang.String`	`diagnose()` Gives info that can be useful for debugging.
`protected void`	`finalize()` Explicitly call `close()` instead to avoid expensive finalization.
`java.util.Collection<java.lang.Class<?>>`	`getAllEntityClasses()`
`static java.lang.Object`	`getContext()`
`static BoxStore`	`getDefault()` Convenience singleton instance which gets set up using `BoxStoreBuilder.buildDefault()`.
`int`	`getEntityTypeIdOrThrow(java.lang.Class<?> entityClass)`
`long`	`getNativeStore()` If you want to use the same ObjectBox store using the C API, e.g.
`int`	`getObjectBrowserPort()`
`static java.lang.Object`	`getRelinker()`
`SyncClient`	`getSyncClient()` Returns the `SyncClient` associated with this store.
`static java.lang.String`	`getVersion()` Gets the Version of ObjectBox Java.
`static java.lang.String`	`getVersionNative()` Gets the Version of ObjectBox Core.
`TxCallback<?>`	`internalFailedReadTxAttemptCallback()`
`int`	`internalQueryAttempts()`
`java.util.concurrent.Future<?>`	`internalScheduleThread(java.lang.Runnable runnable)`
`java.util.concurrent.ExecutorService`	`internalThreadPool()`
`boolean`	`isClosed()`
`static boolean`	`isDatabaseOpen(java.io.File directory)` Using a directory, as configured with `BoxStoreBuilder.directory(File)`, checks if the associated database files are in use by a BoxStore instance.
`static boolean`	`isDatabaseOpen(java.io.File baseDirectoryOrNull, java.lang.String dbNameOrNull)` Using an optional base directory, as configured with `BoxStoreBuilder.baseDirectory(File)`, and an optional database name, as configured with `BoxStoreBuilder.name(String)`, checks if the associated database files are in use by a BoxStore instance.
`static boolean`	`isDatabaseOpen(java.lang.Object context, java.lang.String dbNameOrNull)` Using an Android Context and an optional database name, as configured with `BoxStoreBuilder.name(String)`, checks if the associated database files are in use by a BoxStore instance.
`boolean`	`isDebugRelations()`
`static boolean`	`isObjectBrowserAvailable()`
`boolean`	`isObjectBrowserRunning()`
`boolean`	`isReadOnly()` Whether the store was created using read-only mode.
`static boolean`	`isSyncAvailable()`
`static boolean`	`isSyncServerAvailable()`
`void`	`removeAllObjects()` Removes all objects from all types ("boxes"), e.g.
`void`	`runInReadTx(java.lang.Runnable runnable)` Runs the given runnable inside a read(-only) transaction.
`void`	`runInTx(java.lang.Runnable runnable)` Runs the given runnable inside a transaction.
`void`	`runInTxAsync(java.lang.Runnable runnable, TxCallback<java.lang.Void> callback)` Runs the given Runnable as a transaction in a separate thread.
`void`	`setDbExceptionListener(DbExceptionListener dbExceptionListener)` Sets a listener that will be called when an exception is thrown.
`long`	`sizeOnDisk()` The size in bytes occupied by the data file on disk.
`java.lang.String`	`startObjectBrowser()`
`java.lang.String`	`startObjectBrowser(int port)`
`java.lang.String`	`startObjectBrowser(java.lang.String urlToBindTo)`
`boolean`	`stopObjectBrowser()`
`SubscriptionBuilder<java.lang.Class>`	`subscribe()` A `DataObserver` can be subscribed to data changes using the returned builder.
`<T> SubscriptionBuilder<java.lang.Class<T>>`	`subscribe(java.lang.Class<T> forClass)` Like `subscribe()`, but wires the supplied @`DataObserver` only to the given object class for notifications.
`static void`	`testUnalignedMemoryAccess()` Diagnostics: If this method crashes on a device, please send us the logcat output.
`void`	`unregisterTransaction(io.objectbox.Transaction transaction)`
`long`	`validate(long pageLimit, boolean checkLeafLevel)` Validate database pages, a lower level storage unit (integrity check).

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - JNI_VERSION
```
public static final java.lang.String JNI_VERSION
```
    Change so ReLinker will update native library when using workaround loading.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getContext
```
@Nullable
 @Internal
public static java.lang.Object getContext()
```
  - getRelinker
```
@Nullable
 @Internal
public static java.lang.Object getRelinker()
```
  - getDefault
```
public static BoxStore getDefault()
```
    Convenience singleton instance which gets set up using BoxStoreBuilder.buildDefault().
    Note: for better testability, you can usually avoid singletons by storing a BoxStore instance in some application scope object and pass it along.
  - clearDefaultStore
```
public static boolean clearDefaultStore()
```
    Clears the convenience instance.
    Note: This is usually not required (for testability, please see the comment of getDefault()).
    
    Returns:
    
    true if a default store was available before
  - getVersion
```
public static java.lang.String getVersion()
```
    Gets the Version of ObjectBox Java.
  - getVersionNative
```
public static java.lang.String getVersionNative()
```
    Gets the Version of ObjectBox Core.
  - testUnalignedMemoryAccess
```
public static void testUnalignedMemoryAccess()
```
    Diagnostics: If this method crashes on a device, please send us the logcat output.
  - isObjectBrowserAvailable
```
public static boolean isObjectBrowserAvailable()
```
  - isSyncAvailable
```
public static boolean isSyncAvailable()
```
  - isSyncServerAvailable
```
public static boolean isSyncServerAvailable()
```
  - isDatabaseOpen
```
public static boolean isDatabaseOpen(java.lang.Object context,
                                     @Nullable
                                     java.lang.String dbNameOrNull)
                              throws java.io.IOException
```
    Using an Android Context and an optional database name, as configured with BoxStoreBuilder.name(String), checks if the associated database files are in use by a BoxStore instance.
    Use this to check that database files are not open before copying or deleting them.
    
    Throws:
    
    java.io.IOException
  - isDatabaseOpen
```
public static boolean isDatabaseOpen(@Nullable
                                     java.io.File baseDirectoryOrNull,
                                     @Nullable
                                     java.lang.String dbNameOrNull)
                              throws java.io.IOException
```
    Using an optional base directory, as configured with BoxStoreBuilder.baseDirectory(File), and an optional database name, as configured with BoxStoreBuilder.name(String), checks if the associated database files are in use by a BoxStore instance.
    Use this to check that database files are not open before copying or deleting them.
    
    Throws:
    
    java.io.IOException
  - isDatabaseOpen
```
public static boolean isDatabaseOpen(java.io.File directory)
                              throws java.io.IOException
```
    Using a directory, as configured with BoxStoreBuilder.directory(File), checks if the associated database files are in use by a BoxStore instance.
    Use this to check that database files are not open before copying or deleting them.
    
    Throws:
    
    java.io.IOException
  - sizeOnDisk
```
public long sizeOnDisk()
```
    The size in bytes occupied by the data file on disk.
    
    Returns:
    
    0 if the size could not be determined (does not throw unless this store was already closed)
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Explicitly call close() instead to avoid expensive finalization.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable
  - getEntityTypeIdOrThrow
```
@Internal
public int getEntityTypeIdOrThrow(java.lang.Class<?> entityClass)
```
  - getAllEntityClasses
```
public java.util.Collection<java.lang.Class<?>> getAllEntityClasses()
```
  - beginTx
```
@Internal
public io.objectbox.Transaction beginTx()
```
    Internal, low level method: use runInTx(Runnable) instead.
  - beginReadTx
```
@Internal
public io.objectbox.Transaction beginReadTx()
```
    Internal, low level method: use runInReadTx(Runnable) instead. Begins a transaction for read access only. Note: there may be only one read transaction per thread.
  - isClosed
```
public boolean isClosed()
```
  - isReadOnly
```
public boolean isReadOnly()
```
    Whether the store was created using read-only mode. If true the schema is not updated and write transactions are not possible.
  - close
```
public void close()
```
    Closes the BoxStore and frees associated resources. This method is useful for unit tests; most real applications should open a BoxStore once and keep it open until the app dies.
    WARNING: This is a somewhat delicate thing to do if you have threads running that may potentially still use the BoxStore. This results in undefined behavior, including the possibility of crashing.
    
    Specified by:
    
    close in interface java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
  - deleteAllFiles
```
public boolean deleteAllFiles()
```
    Danger zone! This will delete all data (files) of this BoxStore! You must call close() before and read the docs of that method carefully!
    A safer alternative: use the static deleteAllFiles(File) method before opening the BoxStore.
    
    Returns:
    
    true if the directory 1) was deleted successfully OR 2) did not exist in the first place. Note: If false is returned, any number of files may have been deleted before the failure happened.
  - deleteAllFiles
```
public static boolean deleteAllFiles(java.io.File objectStoreDirectory)
```
    Danger zone! This will delete all files in the given directory!
    No BoxStore may be alive using the given directory.
    If you did not use a custom name with BoxStoreBuilder, you can pass "new File(BoxStoreBuilder.DEFAULT_NAME)".
    
    Parameters:
    
    objectStoreDirectory - directory to be deleted; this is the value you previously provided to BoxStoreBuilder.directory(File)
    
    Returns:
    
    true if the directory 1) was deleted successfully OR 2) did not exist in the first place. Note: If false is returned, any number of files may have been deleted before the failure happened.
    
    Throws:
    
    java.lang.IllegalStateException - if the given directory is still used by a open BoxStore.
  - deleteAllFiles
```
public static boolean deleteAllFiles(java.lang.Object androidContext,
                                     @Nullable
                                     java.lang.String customDbNameOrNull)
```
    Danger zone! This will delete all files in the given directory!
    No BoxStore may be alive using the given name.
    If you did not use a custom name with BoxStoreBuilder, you can pass "new File(BoxStoreBuilder.DEFAULT_NAME)".
    
    Parameters:
    
    androidContext - provide an Android Context like Application or Service
    
    customDbNameOrNull - use null for default name, or the name you previously provided to BoxStoreBuilder.name(String).
    
    Returns:
    
    true if the directory 1) was deleted successfully OR 2) did not exist in the first place. Note: If false is returned, any number of files may have been deleted before the failure happened.
    
    Throws:
    
    java.lang.IllegalStateException - if the given name is still used by a open BoxStore.
  - deleteAllFiles
```
public static boolean deleteAllFiles(@Nullable
                                     java.io.File baseDirectoryOrNull,
                                     @Nullable
                                     java.lang.String customDbNameOrNull)
```
    Danger zone! This will delete all files in the given directory!
    No BoxStore may be alive using the given directory.
    If you did not use a custom name with BoxStoreBuilder, you can pass "new File(BoxStoreBuilder.DEFAULT_NAME)".
    
    Parameters:
    
    baseDirectoryOrNull - use null for no base dir, or the value you previously provided to BoxStoreBuilder.baseDirectory(File)
    
    customDbNameOrNull - use null for default name, or the name you previously provided to BoxStoreBuilder.name(String).
    
    Returns:
    
    true if the directory 1) was deleted successfully OR 2) did not exist in the first place. Note: If false is returned, any number of files may have been deleted before the failure happened.
    
    Throws:
    
    java.lang.IllegalStateException - if the given directory (+name) is still used by a open BoxStore.
  - removeAllObjects
```
public void removeAllObjects()
```
    Removes all objects from all types ("boxes"), e.g. deletes all database content (excluding meta data like the data model). This typically performs very quickly (e.g. faster than Box.removeAll()).
    Note that this does not reclaim disk space: the already reserved space for the DB file(s) is used in the future resulting in better performance because no/less disk allocation has to be done.
    If you want to reclaim disk space, delete the DB file(s) instead:
    - close() the BoxStore (and ensure that no thread access it)
    - deleteAllFiles() of the BoxStore
    - Open a new BoxStore
  - unregisterTransaction
```
@Internal
public void unregisterTransaction(io.objectbox.Transaction transaction)
```
  - boxFor
```
public <T> Box<T> boxFor(java.lang.Class<T> entityClass)
```
    Returns a Box for the given type. Objects are put into (and get from) their individual Box.
    Creates a Box only once and then always returns the cached instance.
  - runInTx
```
public void runInTx(java.lang.Runnable runnable)
```
    Runs the given runnable inside a transaction.
    Efficiency notes: it is advised to run multiple puts in a transaction because each commit requires an expensive disk synchronization.
  - runInReadTx
```
public void runInReadTx(java.lang.Runnable runnable)
```
    Runs the given runnable inside a read(-only) transaction. Multiple read transactions can occur at the same time. This allows multiple read operations (gets) using a single consistent state of data. Also, for a high number of read operations (thousands, e.g. in loops), it is advised to run them in a single read transaction for efficiency reasons.
  - callInReadTxWithRetry
```
@Experimental
public <T> T callInReadTxWithRetry(java.util.concurrent.Callable<T> callable,
                                                 int attempts,
                                                 int initialBackOffInMs,
                                                 boolean logAndHeal)
```
    Calls callInReadTx(Callable) and retries in case a DbException is thrown. If the given amount of attempts is reached, the last DbException will be thrown. Experimental: API might change.
  - callInReadTx
```
public <T> T callInReadTx(java.util.concurrent.Callable<T> callable)
```
    Calls the given callable inside a read(-only) transaction. Multiple read transactions can occur at the same time. This allows multiple read operations (gets) using a single consistent state of data. Also, for a high number of read operations (thousands, e.g. in loops), it is advised to run them in a single read transaction for efficiency reasons. Note that an exception thrown by the given Callable will be wrapped in a RuntimeException, if the exception is not a RuntimeException itself.
  - callInTx
```
public <R> R callInTx(java.util.concurrent.Callable<R> callable)
               throws java.lang.Exception
```
    Like runInTx(Runnable), but allows returning a value and throwing an exception.
    
    Throws:
    
    java.lang.Exception
  - callInTxNoException
```
public <R> R callInTxNoException(java.util.concurrent.Callable<R> callable)
```
    Like callInTx(Callable), but throws no Exception. Any Exception thrown in the Callable is wrapped in a RuntimeException.
  - runInTxAsync
```
public void runInTxAsync(java.lang.Runnable runnable,
                         @Nullable
                         TxCallback<java.lang.Void> callback)
```
    Runs the given Runnable as a transaction in a separate thread. Once the transaction completes the given callback is called (callback may be null).
    See also runInTx(Runnable).
  - callInTxAsync
```
public <R> void callInTxAsync(java.util.concurrent.Callable<R> callable,
                              @Nullable
                              TxCallback<R> callback)
```
    Runs the given Runnable as a transaction in a separate thread. Once the transaction completes the given callback is called (callback may be null).
    * See also callInTx(Callable).
  - diagnose
```
public java.lang.String diagnose()
```
    Gives info that can be useful for debugging.
    
    Returns:
    
    String that is typically logged by the application.
  - validate
```
@Beta
public long validate(long pageLimit,
                           boolean checkLeafLevel)
```
    Validate database pages, a lower level storage unit (integrity check). Do not call this inside a transaction (currently unsupported).
    
    Parameters:
    
    pageLimit - the maximum of pages to validate (e.g. to limit time spent on validation). Pass zero set no limit and thus validate all pages.
    
    checkLeafLevel - Flag to validate leaf pages. These do not point to other pages but contain data.
    
    Returns:
    
    Number of pages validated, which may be twice the given pageLimit as internally there are "two DBs".
    
    Throws:
    
    DbException - if validation failed to run (does not tell anything about DB file consistency).
    
    FileCorruptException - if the DB file is actually inconsistent (corrupt).
  - cleanStaleReadTransactions
```
public int cleanStaleReadTransactions()
```
  - closeThreadResources
```
public void closeThreadResources()
```
    Call this method from a thread that is about to be shutdown or likely not to use ObjectBox anymore: it frees any cached resources tied to the calling thread (e.g. readers). This method calls Box.closeThreadResources() for all initiated boxes (boxFor(Class)).
  - subscribe
```
public SubscriptionBuilder<java.lang.Class> subscribe()
```
    A DataObserver can be subscribed to data changes using the returned builder. The observer is supplied via SubscriptionBuilder.observer(DataObserver) and will be notified once a transaction is committed and will receive changes to any object class.
    Threading notes: All observers are notified from one separate thread (pooled). Observers are not notified in parallel. The notification order is the same as the subscription order, although this may not always be guaranteed in the future.
    Note that failed or aborted transaction do not trigger observers.
  - startObjectBrowser
```
@Experimental
 @Nullable
public java.lang.String startObjectBrowser()
```
  - startObjectBrowser
```
@Experimental
 @Nullable
public java.lang.String startObjectBrowser(int port)
```
  - startObjectBrowser
```
@Experimental
 @Nullable
public java.lang.String startObjectBrowser(java.lang.String urlToBindTo)
```
  - stopObjectBrowser
```
@Experimental
public boolean stopObjectBrowser()
```
  - getObjectBrowserPort
```
@Experimental
public int getObjectBrowserPort()
```
  - isObjectBrowserRunning
```
public boolean isObjectBrowserRunning()
```
  - setDbExceptionListener
```
public void setDbExceptionListener(@Nullable
                                   DbExceptionListener dbExceptionListener)
```
    Sets a listener that will be called when an exception is thrown. Replaces a previously set listener. Set to null to remove the listener.
    This for example allows central error handling or special logging for database-related exceptions.
  - subscribe
```
public <T> SubscriptionBuilder<java.lang.Class<T>> subscribe(java.lang.Class<T> forClass)
```
    Like subscribe(), but wires the supplied @DataObserver only to the given object class for notifications.
  - internalScheduleThread
```
@Internal
public java.util.concurrent.Future<?> internalScheduleThread(java.lang.Runnable runnable)
```
  - internalThreadPool
```
@Internal
public java.util.concurrent.ExecutorService internalThreadPool()
```
  - isDebugRelations
```
@Internal
public boolean isDebugRelations()
```
  - internalQueryAttempts
```
@Internal
public int internalQueryAttempts()
```
  - internalFailedReadTxAttemptCallback
```
@Internal
public TxCallback<?> internalFailedReadTxAttemptCallback()
```
  - getNativeStore
```
public long getNativeStore()
```
    If you want to use the same ObjectBox store using the C API, e.g. via JNI, this gives the required pointer, which you have to pass on to obx_store_wrap(). The procedure is like this:
    1) you create a BoxStore on the Java side
    2) you call this method to get the native store pointer
    3) you pass the native store pointer to your native code (e.g. via JNI)
    4) your native code calls obx_store_wrap() with the native store pointer to get a OBX_store pointer
    5) Using the OBX_store pointer, you can use the C API.
    Note: Once you close() this BoxStore, do not use it from the C API.
  - getSyncClient
```
@Nullable
public SyncClient getSyncClient()
```
    Returns the SyncClient associated with this store. To create one see Sync.

Class BoxStore

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

JNI_VERSION

Method Detail

getContext

getRelinker

getDefault

clearDefaultStore

getVersion

getVersionNative

testUnalignedMemoryAccess

isObjectBrowserAvailable

isSyncAvailable

isSyncServerAvailable

isDatabaseOpen

isDatabaseOpen

isDatabaseOpen

sizeOnDisk

finalize

getEntityTypeIdOrThrow

getAllEntityClasses

beginTx

beginReadTx

isClosed

isReadOnly

close

deleteAllFiles

deleteAllFiles

deleteAllFiles

deleteAllFiles

removeAllObjects

unregisterTransaction

boxFor

runInTx

runInReadTx

callInReadTxWithRetry

callInReadTx

callInTx

callInTxNoException

runInTxAsync

callInTxAsync

diagnose

validate

cleanStaleReadTransactions

closeThreadResources

subscribe

startObjectBrowser

startObjectBrowser

startObjectBrowser

stopObjectBrowser

getObjectBrowserPort

isObjectBrowserRunning

setDbExceptionListener

subscribe

internalScheduleThread

internalThreadPool

isDebugRelations

internalQueryAttempts

internalFailedReadTxAttemptCallback

getNativeStore

getSyncClient