Package io.objectbox

Class BoxStoreBuilder

java.lang.Object
io.objectbox.BoxStoreBuilder
public class BoxStoreBuilder extends 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 Details

    • DEFAULT_NAME

      public static final String DEFAULT_NAME
      The default DB name, which can be overwritten using name(String).
      See Also:

    • 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:

  • Constructor Details

    • BoxStoreBuilder

      @Internal public BoxStoreBuilder(byte[] model)
      Called internally from the generated class "MyObjectBox". Check MyObjectBox.builder() to get an instance.

  • Method Details

    • createDebugWithoutModel

      @Internal public static BoxStoreBuilder createDebugWithoutModel()
      Not for application use, for DebugCursor.

    • name

      public BoxStoreBuilder name(String name)
      Name of the database, which will be used as a directory for database files. You can also specify a base directory for this one using baseDirectory(File). Cannot be used in combination with directory(File) and inMemory(String).

      Default: "objectbox", DEFAULT_NAME (unless directory(File) is used)

    • directory

      public BoxStoreBuilder directory(File directory)
      The directory where all database files should be placed in.

      If the directory does not exist, it will be created. Make sure the process has permissions to write to this directory.

      To switch to an in-memory database, use a file path with BoxStore.IN_MEMORY_PREFIX and an identifier instead: 

      
 BoxStore inMemoryStore = MyObjectBox.builder()
     .directory(BoxStore.IN_MEMORY_PREFIX + "notes-db")
     .build();
      Alternatively, use inMemory(String).

      Can not be used in combination with name(String), baseDirectory(File) or inMemory(String).

    • baseDirectory

      public BoxStoreBuilder baseDirectory(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) or inMemory(String).

    • inMemory

      public BoxStoreBuilder inMemory(String identifier)
      Switches to an in-memory database using the given name as its identifier.

      Can not be used in combination with name(String), directory(File) or baseDirectory(File).

    • androidContext

      public BoxStoreBuilder androidContext(Object context)
      Use on Android to pass a Context for loading the native library and, if not an inMemory(String) database, for creating the base directory for database files in the files directory of the app.

      In more detail, upon build() 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 database files will be "objectbox/objectbox/" inside the app's files directory. If a custom name is specified, for example with name("foobar"), it would become "objectbox/foobar/".

      Use baseDirectory(File) or directory(File) to specify a different directory for the database files.

    • androidReLinker

      public BoxStoreBuilder androidReLinker(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 (about 126 readers).

      A "reader" is short for a thread involved in a read transaction. If the maximum is exceeded the store throws DbMaxReadersExceededException. In this case check that your code only uses a reasonable amount of threads.

      For highly concurrent setups (e.g. you are using ObjectBox on the server side) it may make sense to increase the number.

      Note: Each thread that performed a read transaction and is still alive holds on to a reader slot. These slots only get vacated when the thread ends. Thus, be mindful with the number of active threads. Alternatively, you can try the experimental noReaderThreadLocals() option flag.

    • noReaderThreadLocals

      public BoxStoreBuilder noReaderThreadLocals()
      Disables the usage of thread locals for "readers" related to read transactions. This can make sense if you are using a lot of threads that are kept alive.

      Note: This is still experimental, as it comes with subtle behavior changes at a low level and may affect corner cases with e.g. transactions, which may not be fully tested at the moment.

    • entity

      @Internal public void entity(EntityInfo<?> entityInfo)

    • maxSizeInKByte

      public BoxStoreBuilder maxSizeInKByte(long maxSizeInKByte)
      Sets the maximum size the database file can grow to.

      The Store will throw when the file size is about to be exceeded, see DbFullException for details.

      By default, this is 1 GB, which should be sufficient for most applications. In general, a maximum size prevents the database from growing indefinitely when something goes wrong (for example data is put in an infinite loop).

      This can be set to a value different, so higher or also lower, from when last building the Store.

    • maxDataSizeInKByte

      public BoxStoreBuilder maxDataSizeInKByte(long maxDataSizeInKByte)
      Sets the maximum size the data stored in the database can grow to. When applying a transaction (e.g. putting an object) would exceed it a DbMaxDataSizeExceededException is thrown.

      Must be below maxSizeInKByte(long).

      Different from maxSizeInKByte(long) this only counts bytes stored in objects, excluding system and metadata. However, it is more involved than database size tracking, e.g. it stores an internal counter. Only use this if a stricter, more accurate limit is required.

      When the data limit is reached, data can be removed to get below the limit again (assuming the database size limit is not also reached).

    • 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 validateOnOpenModePages)
      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.

      See also validateOnOpenPageLimit(long) to fine-tune this check and validateOnOpenKv(short) for additional checks.

      Parameters:
      validateOnOpenModePages - One of ValidateOnOpenModePages.

    • 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 ValidateOnOpenModePages.Regular and ValidateOnOpenModePages.WithLeaves.

    • validateOnOpenKv

      public BoxStoreBuilder validateOnOpenKv()
      When a database is opened, ObjectBox can perform additional consistency checks on its database structure. This enables validation checks on a key/value level.

      This is a shortcut for validateOnOpenKv(ValidateOnOpenModeKv.Regular).

    • validateOnOpenKv

      public BoxStoreBuilder validateOnOpenKv(short mode)
      When a database is opened, ObjectBox can perform additional consistency checks on its database structure. This enables validation checks on a key/value level.

      See also validateOnOpen(short) for additional consistency checks.

      Parameters:
      mode - One of ValidateOnOpenModeKv.

    • 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(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<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 the current configuration of this builder.

      If androidContext(Object) was called and no directory(File) or baseDirectory(File) is configured, creates and sets baseDirectory(File) as explained in androidContext(Object).

    • 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).