ObjectBox is an an easy to use, object-oriented lightweight database and a full alternative to SQLite.
This is the ObjectBox documentation for our Java API. We strive to provide you with the easiest and fastest solution to store and retrieve data. Your feedback on ObjectBox and this documentation is very welcome. Use the "Was this page helpful?" smiley at the end of each page or send us your comments to contact[at]objectbox.io - thank you! :)
Using @Unique for strings? Please update ASAP
Urgent fix: the unique check for string properties had false positives resulting in UniqueViolationException. This occurs only in combination with IndexType.HASH (the default) when hashes actually collide. We advise to update immediately to the newest version if you are using hashed indexes.
The release of new ObjectBox C API made us change name of the JNI library
for better distinction. This should not affect you unless you depended on that (internal) name.
Improved compatibility with class transformers like Jacoco
Fixed query links for M:N backlinks
Improved error messages for the build tools
The Object Browser AAR now includes the required Android permissions
Entity counts are now cached for better performance
Deprecated aggregate function were removed (deprecation in 1.4 with introduction of PropertyQuery)
Object browser hot fix: the hashed indexes introduced in 2.0 broke the object browser
Object browser fixes: filters with long ints, improved performance in the schema view
NPE fix in ToOne
Added a specific NonUniqueResultException if a query did not return an expected unique result
Links and relation completeness and other features already announced in the 2.0 beta
Unique constraint for properties via @Unique annotation
Hash index: for strings the new default index is hash-based, which is more space efficient
Support for char type (16 bit)
RX lib deployed in JCenter
Rework of Query APIs: type safe properties (property now knows its owning entity)
Allow query conditions of links using properties (without parameter alias)
Query performance improvements when using order
Property based count: query for non-null or unique occurrences of entity properties (non-null and unique)
Additional query conditions for strings: "greater than", "less than", "in"
Added query conditions for byte arrays
Set query parameters for "in" condition (int and long)
Query across relation bounds using links (aka "join"): queries just got much more powerful. For example, query for orders that have a customer with an address on "Sesame Street". Or all persons, who have a grand parent called "Alice".
Backlinks for to-many relations: now ObjectBox is "relation complete" with a bi-directional many-to-many relation.
Query performance improvements: getting min/max values of indexed properties in constant time
Android: added Paging library support (architecture components)
Kotlin extensions: more Kotlin fun with ObjectBox KTX
Query parameters aliases: helps setting query parameters in complex scenarios (e.g. for properties of linked entities)
Improved query parameter verification
Many internal improvements to keep us going fast in the future
Full support for Android local tests: use full ObjectBox features in local tests
New count method optimized for a given maximum count
Gradle option to define the package for MyObjectBox explicitly
Query condition startsWith now uses index if available for better performance
Fixed some static methods in BoxStore to ensure that the native lib is loaded
Internal optimizations for 64 bit devices
Some fixes for entities in the default package
Entity can be named
Property, no longer conflicts with ObjectBox Property class
Property queries for strings crashed on some Android devices if there were more than 512 results
Object Browser uses less threads
Object Browser now displays negative int/long values correctly
Changes to relations object in constructors were overwritten when constructors delegated to other constructors
Supply an initial database file using BoxStoreBuilder
Gradle plugin detects plain Java projects and configures dependencies
Improved Box.removeAll() performance for entities that have indexes or relations
Fixed converting from arrays in entities
Fixed Gradle “androidTestCompile is obsolete” warning
macOS support: with Linux, Windows, and macOS, ObjectBox now supports all major desktop/server platforms. Use it for local unit tests or standalone Java applications.
Fixed BoxStore.close being stuck in rare scenarios
Fixed an issue with char properties in entities
Note: This release requires the Android Gradle Plugin 3.0.0 or higher.
JCenter: we’ve moved the ObjectBox artifacts to the JCenter repository. This simplifies set up and improves accessibility (e.g. JCenter is not blocked from China).
Instant App support (only with Android Gradle Plugin 3.0.0 or higher)
Added DbExceptionListener as a central place to listen for DB related exceptions
Minor improvements for ToMany and generated Cursor classes
ToMany: fixed handling of duplicate entries (e.g. fixes swap and reverse operations)
ToMany: fixed removal of non-persisted element for standalone relations
Property queries that return individual properties only (including distinct values, unique, null values, primitive result arrays or scalars)
Entity inheritance (non-polymorphic)
50% size reduction of native libraries
ToOne now implements equals() and hashCode() based on the targetId property
Android ABI x86_64 was added to the aar
ID verification does not complain about “resurrected” objects that were loaded, removed, and put again
Fixed setting Query parameters for Date type
Fixes for ObjectBox browser
Please update to the latest version. We made important changes and fixes under the hood to make ObjectBox perform better, generally, and especially in concurrent scenarios. In addition, 1.3.x comes with several improvements for developers.
Object browser lets you download all entities as JSON
Object browser efficiency improvements: introduced streamed processing to reduce memory consumption and increase performance for large data sets
Improved transaction logging, e.g. numbered transactions and waiting times for write transactions
Closing the store (e.g. for tests, an app should just leave it open) will wait for any ongoing write transaction to finish
Two additional overloads for static BoxStore.deleteAllFiles()
Added automatic retries for read transactions; also configurable for queries
Fixes for concurrent setups (multi threaded, in live apps with up to 100 threads); internally we improved our testing automation and CI infrastructure significantly
Fix for sumDouble throwing an exception
Fixed ProGuard rule for ToOne
Improved debug logging for transactions and queries: enable this using BoxStoreBuilder.debugFlags(…) with values from the DebugFlags class
Improved package selection for MyObjectBox if you use entities in multiple packages (please check if you need to adjust your imports after the update)
ObjectBox Browser’s UI is more compact and thus better usable on mobile devices
Fix for ObjectBoxLiveData firing twice
Compatibility note: We removed some Box.find methods, which were all tagged as @Temporary. Only the Property based ones remain (for now, also @Temporary).
ObjectBoxLiveData: Implements LiveData from Android Architecture Components
Object ID based methods for ToMany: getById, indexOfId, removeById
More robust Android app directory detection that works around Android bugs
Using the new official FlatBuffers Maven dependency (FlatBuffer is not anymore embedded in the artifact)
UI improvements for ObjectBox browser
Other minor improvements
Fixed query order by float and double
Fixed an missing import if to-many relations referenced a entity in another package
Other minor fixes
Object Browser to view DB contents (Android)
Plain Java support to run ObjectBox on Windows and Linux
Added ToMany.hasA()/hasAll() to simplify query filters in Java
Sort query result via Comparator
Improved error messages on build errors
Internal clean up, dropping legacy plugin
Annotation processor detects boolean getters starting with “is”
Fixed a NPE with eager and findFirst() when there is no result
First bug fix release for ObjectBox 1.0.
ToMany allows setting a Comparator to order the List (experimental)
Fix UID assignment process: use @Uid without value to see options (pin UID, reset/change)
Fix relation code generation for entities in different packages
Fix Kotlin extension functions in transformed (library) project
Fix ToOne access if field is inaccessible (e.g. in Kotlin data classes if they are part of constructor – lateinit were OK)
ObjectBox is out of beta! See our announcement blog post for details.
Eager loading of relations via query builder
Java filters as query post-processing
Minor improvements like a new callInReadTx method and making Query.forEach breakable
Fixed two corner cases with queries
Fixed: Android flavors in caused the model file (default.json) to be written into the wrong folder (inside the build folder) causing the build to fail
Fixed: failed builds if entity constructor parameters are of specific types
For upgrade notes, please check the announcement post.
No more in-place code generation: Java source code is all yours now. This is based on the new build tool chain introduced in 0.9.13. Thus Kotlin and Java share the same build system. The old Java-based plugin is still available (plugin ID “io.objectbox.legacy”) in this version.
“Standalone” to-many relations (without backing to-one properties/relations)
Gradle plugin tries to automatically add runtime dependencies (also (k)apt, but this does not always work!?)
Improved error reporting
Fixed the issue causing a “Illegal state: Tx destroyed/inactive, writeable cursor still available” error log
Kotlin support (based on a new annotation processor)
Started “object-kotlin”, a sub-project for Kotlin extensions (tiny yet, let us know your ideas!)
BoxStoreBuilder: added maxReaders configuration
Get multiple entities by their IDs via Box methods (see get/getMap(Iterable))
ToOne and ToMany are now serializable (which does not imply serializing is a good idea)
ObjectBox may now opt to construct entities using the no-args constructor if the all-args constructor is absent
Prevents opening two BoxStores for the same DB file, which may have side effects that are hard to debug
Various minor and internal improvements and fixes
Fixed ToOne without an explicit target ID property
Fixed type check of properties to allow ToMany (instead of List)
Fixed @Convert in combination with List
Fixed a race condition with cursor deletion when Java’s finalizer kicked in potentially resulting in a SIGSEGV
Fixed a leak with potentially occurring with indexes
Update 2017/05/19: We just released 0.9.12.1 for the Gradle plugin (only), which fixes two problems with parsing of to-many relations.
Added the new list type ToMany which represents a to-many relation. A ToMany object will be automatically assigned to List types in the entity, eliminating a lot of generated code in the entity.
ToMany comes with change tracking: all changes (add/remove) are automatically applied to the DB when its hosting entity is persisted via put(). Thus, the list content is synced to the DB, e.g. their relationship status is updated and new entities are put.
Streamlined annotations (breaking API changes): @Generated(hash = 123) becomes @Generated(123), @Property was removed, @NameInDb replaces attributes in @Entity and the former @Property, Backlinking to-many relations require @Backlink (only), @Relation is now only used for to-one relations (and is subject to change in the next version)
Smarter to-one relations: if you put a new object that also has a new to-one relation object, the latter will also be put automatically.
Getters and setters for properties are now only generated if no direct field access is possible
JSR-305 annotations (@Nullable and others) to help the IDE find problems in your code
@Uid(-1) will reassign IDs to simplify some migrations (docs will follow soon)
No more getter for ToOne objects in favor of direct field access
Quite a few internal improvements (evolved EntityInfo meta info object, etc.)
Breaking API: Replaced “uid” attribute of @Entity and @Property with @Uid annotation
An empty @Uid will retrieve the current UID automatically
Some minor efficency improvements for read transactions
Better DB resources clean up for internal thread pool
Better compatibility with Android Gradle plugin
Fixes for multithreaded reads of relation and index data
Fixed compilation error in generated sources for Entities without non-ID properties
Query.forEach() to iterate efficiently over query result objects
Various bug fixes
Data observers with reactive extensions for transformations, thread scheduling, etc.
Optional RxJava 2 library
OR conditions for QueryBuilder allow more powerful queries
Fixed: Changing the order of an entity’s properties could cause errors in some cases
Fixed: Querying using relation IDs
LazyList returned by Query: another query option to defer getting actual objects until actually accessing them. This enables memory efficient iterations over large results. Also minimizes the time for a query to return. Note: LazyList cannot be combined with order specifications just yet.
QueryBuilder and Query now support Date and boolean types directly
QueryBuilder supports now a notIn opperator
put() now uses entity fields directly unless they are private (can be more efficient than calling getters)
At this early point in the beta we decided to break backward compatibility. This allowed us to make important improvements without worrying about rather complex migrations of previous versions. We believe this was a special situation and future versions will likely be backward compatible although we cannot make promises. If you intend to publish an app with ObjectBox it’s a good idea to contact us before.
The internal data format was optimized to store data more compact. Previous database files are not compatible and should be deleted.
We improved some details how IDs are used in the meta model. This affects the model file, which is stored in your project directory (objectbox-models/default.json). Files created by previous versions should be deleted.