BoxStoreBuilder (objectbox-java 2.9.2-RC API)

java.lang.Object
- io.objectbox.BoxStoreBuilder

```
public class BoxStoreBuilder
extends java.lang.Object
```
Configures and builds a BoxStore with reasonable defaults. To get an instance use MyObjectBox.builder().
On Android, make sure to provide a Context to androidContext(context).
Some common defaults to override are:
1. Name/location of Store: use either name(String), baseDirectory(File), androidContext(Object) or directory(File) (default: name "objectbox),
2. Max DB size: see maxSizeInKByte(long) (default: 1024 * 1024 KB = 1 GB),
3. Max readers: see maxReaders(int) (default: 126),

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_MAX_DB_SIZE_KBYTE` The default maximum size the DB can grow to, which can be overwritten using `maxSizeInKByte`.
`static java.lang.String`	`DEFAULT_NAME` The default DB name, which can be overwritten using `name(String)`.

Constructor Summary

Constructors
Constructor and Description

BoxStoreBuilder(byte[] model)
Called internally from the generated class "MyObjectBox".

Constructors
Constructor and Description
`BoxStoreBuilder(byte[] model)` Called internally from the generated class "MyObjectBox".

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`BoxStoreBuilder`	`androidContext(java.lang.Object context)` On Android, you can pass a Context to set the base directory using this method.
`BoxStoreBuilder`	`androidReLinker(java.lang.Object reLinkerInstance)` Pass a custom ReLinkerInstance, for example `ReLinker.log(logger)` to use for loading the native library on Android devices.
`BoxStoreBuilder`	`baseDirectory(java.io.File baseDirectory)` In combination with `name(String)`, this lets you specify the location of where the DB files should be stored.
`BoxStore`	`build()` Builds a `BoxStore` using any given configuration.
`BoxStore`	`buildDefault()` Builds the default `BoxStore` instance, which can be acquired using `BoxStore.getDefault()`.
`static BoxStoreBuilder`	`createDebugWithoutModel()` Not for application use, for DebugCursor.
`BoxStoreBuilder`	`debugFlags(int debugFlags)` Debug flags typically enable additional logging, see `DebugFlags` for valid values.
`BoxStoreBuilder`	`debugRelations()` Enables some debug logging for relations.
`BoxStoreBuilder`	`debugTransactions()` Deprecated. Use `debugFlags` instead.
`BoxStoreBuilder`	`directory(java.io.File directory)` The directory where all DB files should be placed in.
`void`	`entity(EntityInfo<?> entityInfo)`
`BoxStoreBuilder`	`failedReadTxAttemptCallback(TxCallback<?> failedReadTxAttemptCallback)` Define a callback for failed read transactions during retires (see also `queryAttempts(int)`).
`BoxStoreBuilder`	`fileMode(int mode)` Specify unix-style file permissions for database files.
`BoxStoreBuilder`	`initialDbFile(Factory<java.io.InputStream> initialDbFileFactory)` Let's you specify a provider for a DB file to be used during initial start of the app (no DB file exists yet).
`BoxStoreBuilder`	`initialDbFile(java.io.File initialDbFile)` Let's you specify an DB file to be used during initial start of the app (no DB file exists yet).
`BoxStoreBuilder`	`maxReaders(int maxReaders)` Sets the maximum number of concurrent readers.
`BoxStoreBuilder`	`maxSizeInKByte(long maxSizeInKByte)` Sets the maximum size the database file can grow to.
`BoxStoreBuilder`	`name(java.lang.String name)` Name of the database, which will be used as a directory for DB files.
`BoxStoreBuilder`	`queryAttempts(int queryAttempts)` For massive concurrent setups (app is using a lot of threads), you can enable automatic retries for queries.
`BoxStoreBuilder`	`readOnly()` Open the store in read-only mode: no schema update, no write transactions are allowed (would throw).
`BoxStoreBuilder`	`usePreviousCommit()` Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead.
`BoxStoreBuilder`	`validateOnOpen(short validateOnOpenMode)` When a database is opened, ObjectBox can perform additional consistency checks on its database structure.
`BoxStoreBuilder`	`validateOnOpenPageLimit(long limit)` To fine-tune `validateOnOpen(short)`, you can specify a limit on how much data is looked at.

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

- Field Detail
  - DEFAULT_NAME
```
public static final java.lang.String DEFAULT_NAME
```
    The default DB name, which can be overwritten using name(String).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_DB_SIZE_KBYTE
```
public static final int DEFAULT_MAX_DB_SIZE_KBYTE
```
    The default maximum size the DB can grow to, which can be overwritten using maxSizeInKByte.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - BoxStoreBuilder
```
@Internal
public BoxStoreBuilder(byte[] model)
```
    Called internally from the generated class "MyObjectBox". Check MyObjectBox.builder() to get an instance.
- Method Detail
  - createDebugWithoutModel
```
@Internal
public static BoxStoreBuilder createDebugWithoutModel()
```
    Not for application use, for DebugCursor.
  - name
```
public BoxStoreBuilder name(java.lang.String name)
```
    Name of the database, which will be used as a directory for DB files. You can also specify a base directory for this one using baseDirectory(File). Cannot be used in combination with directory(File).
    Default: "objectbox", DEFAULT_NAME (unless directory(File) is used)
  - directory
```
public BoxStoreBuilder directory(java.io.File directory)
```
    The directory where all DB files should be placed in. Cannot be used in combination with name(String)/baseDirectory(File).
  - baseDirectory
```
public BoxStoreBuilder baseDirectory(java.io.File baseDirectory)
```
    In combination with name(String), this lets you specify the location of where the DB files should be stored. Cannot be used in combination with directory(File).
  - androidContext
```
public BoxStoreBuilder androidContext(java.lang.Object context)
```
    On Android, you can pass a Context to set the base directory using this method. This will conveniently configure the storage location to be in the files directory of your app.
    In more detail, this assigns the base directory (see baseDirectory) to context.getFilesDir() + "/objectbox/". Thus, when using the default name (also "objectbox" unless overwritten using name(String)), the default location of DB files will be "objectbox/objectbox/" inside the app files directory. If you specify a custom name, for example with name("foobar"), it would become "objectbox/foobar/".
    Alternatively, you can also use baseDirectory or directory(File) instead.
  - androidReLinker
```
public BoxStoreBuilder androidReLinker(java.lang.Object reLinkerInstance)
```
    Pass a custom ReLinkerInstance, for example ReLinker.log(logger) to use for loading the native library on Android devices. Note that setting androidContext(Object) is required for ReLinker to work.
  - fileMode
```
public BoxStoreBuilder fileMode(int mode)
```
    Specify unix-style file permissions for database files. E.g. for -rw-r---- (owner, group, other) pass the octal code 0640. Any newly generated directory additionally gets searchable (01) for groups with read or write permissions. It's not allowed to pass in an executable flag.
  - maxReaders
```
public BoxStoreBuilder maxReaders(int maxReaders)
```
    Sets the maximum number of concurrent readers. For most applications, the default is fine (> 100 readers).
    A "reader" is short for a thread involved in a read transaction.
    If you hit DbMaxReadersExceededException, you should first worry about the amount of threads you are using. For highly concurrent setups (e.g. you are using ObjectBox on the server side) it may make sense to increase the number.
  - entity
```
@Internal
public void entity(EntityInfo<?> entityInfo)
```
  - maxSizeInKByte
```
public BoxStoreBuilder maxSizeInKByte(long maxSizeInKByte)
```
    Sets the maximum size the database file can grow to. By default this is 1 GB, which should be sufficient for most applications.
    In general, a maximum size prevents the DB from growing indefinitely when something goes wrong (for example you insert data in an infinite loop).
  - readOnly
```
public BoxStoreBuilder readOnly()
```
    Open the store in read-only mode: no schema update, no write transactions are allowed (would throw).
  - usePreviousCommit
```
public BoxStoreBuilder usePreviousCommit()
```
    Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead. When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest transaction.
    To ensure no data is lost accidentally, it is recommended to use this in combination with readOnly() to examine and validate the database first.
  - validateOnOpen
```
public BoxStoreBuilder validateOnOpen(short validateOnOpenMode)
```
    When a database is opened, ObjectBox can perform additional consistency checks on its database structure. Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable OSes, file systems, or hardware.
    Note: ObjectBox builds upon ACID storage, which already has strong consistency mechanisms in place.
    
    Parameters:
    
    validateOnOpenMode - One of ValidateOnOpenMode.
  - validateOnOpenPageLimit
```
public BoxStoreBuilder validateOnOpenPageLimit(long limit)
```
    To fine-tune validateOnOpen(short), you can specify a limit on how much data is looked at. This is measured in "pages" with a page typically holding 4000. Usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly.
    This can only be used with ValidateOnOpenMode.Regular and ValidateOnOpenMode.WithLeaves.
  - debugTransactions
```
@Deprecated
public BoxStoreBuilder debugTransactions()
```
    Deprecated. Use debugFlags instead.
  - debugFlags
```
public BoxStoreBuilder debugFlags(int debugFlags)
```
    Debug flags typically enable additional logging, see DebugFlags for valid values.
    Example: debugFlags(DebugFlags.LOG_TRANSACTIONS_READ | DebugFlags.LOG_TRANSACTIONS_WRITE);
  - debugRelations
```
public BoxStoreBuilder debugRelations()
```
    Enables some debug logging for relations.
  - queryAttempts
```
@Experimental
public BoxStoreBuilder queryAttempts(int queryAttempts)
```
    For massive concurrent setups (app is using a lot of threads), you can enable automatic retries for queries. This can resolve situations in which resources are getting sparse (e.g. DbMaxReadersExceededException or other variations of DbException are thrown during query execution).
    
    Parameters:
    
    queryAttempts - number of attempts a query find operation will be executed before failing. Recommended values are in the range of 2 to 5, e.g. a value of 3 as a starting point.
  - failedReadTxAttemptCallback
```
@Experimental
public BoxStoreBuilder failedReadTxAttemptCallback(TxCallback<?> failedReadTxAttemptCallback)
```
    Define a callback for failed read transactions during retires (see also queryAttempts(int)). Useful for e.g. logging.
  - initialDbFile
```
@Experimental
public BoxStoreBuilder initialDbFile(java.io.File initialDbFile)
```
    Let's you specify an DB file to be used during initial start of the app (no DB file exists yet).
  - initialDbFile
```
@Experimental
public BoxStoreBuilder initialDbFile(Factory<java.io.InputStream> initialDbFileFactory)
```
    Let's you specify a provider for a DB file to be used during initial start of the app (no DB file exists yet). The provider will only be called if no DB file exists yet.
  - build
```
public BoxStore build()
```
    Builds a BoxStore using any given configuration.
  - buildDefault
```
public BoxStore buildDefault()
```
    Builds the default BoxStore instance, which can be acquired using BoxStore.getDefault(). For testability, please see the comment of BoxStore.getDefault().
    May be called once only (throws otherwise).

Class BoxStoreBuilder

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_NAME

DEFAULT_MAX_DB_SIZE_KBYTE

Constructor Detail

BoxStoreBuilder

Method Detail

createDebugWithoutModel

name

directory

baseDirectory

androidContext

androidReLinker

fileMode

maxReaders

entity

maxSizeInKByte

readOnly

usePreviousCommit

validateOnOpen

validateOnOpenPageLimit

debugTransactions

debugFlags

debugRelations

queryAttempts

failedReadTxAttemptCallback

initialDbFile

initialDbFile

build

buildDefault