ObjectBox - Custom Types

Custom types allow entities to have properties of any type (class). This is based on mapping built-in types to custom classes. ObjectBox has the following built-in (Java) types:

boolean, Boolean
int, Integer
short, Short
long, Long
float, Float
double, Double
byte, Byte
char, Character
byte[]
String
Date

Convert annotation and property converter

To add support for a custom type, you can map properties to one of the built-in types using a @Convert annotation. You also need to provide a PropertyConverter implementation.

For example, you could define a color in your entity using a custom Color class and map it to an Integer. Or you can map the popular org.joda.time.DateTime from Joda Time to a Long.

Here is an example mapping an enum to an Integer:

@Entity
public class User {
    @Id
    private Long id;
    
    @Convert(converter = RoleConverter.class, dbType = Integer.class)
    private Role role;
    
    public enum Role {
        DEFAULT(0), AUTHOR(1), ADMIN(2);
        
        final int id;
        
        Role(int id) {
            this.id = id;
        }
    }
    
    public static class RoleConverter implements PropertyConverter<Role, Integer>; {
        @Override
        public Role convertToEntityProperty(Integer databaseValue) {
            if (databaseValue == null) {
                return null;
            }
            for (Role role : Role.values()) {
                if (role.id == databaseValue) {
                    return role;
                }
            }
            return Role.DEFAULT;
        }
    
        @Override
        public Integer convertToDatabaseValue(Role entityProperty) {
            return entityProperty == null ? null : entityProperty.id;
        }
    }
}

Things to look out for

If you define your custom type or converter inside your entity class, they have to be static.

Don’t forget to handle null values correctly – usually you should return null if the input is null.

Database types in the sense of the converter are the primitive Java types offered by ObjectBox, as mentioned in the beginning. It is recommended to use a primitive type that is easily convertible (int, long, byte array, String, …).

You must not interact with the database (such as using Box or BoxStore) inside the converter. The converter methods are called within a transaction, so for example getting or putting entities to a box will fail.

List/Array types

You can use a converter with List types. For example, you could convert a List of Strings to a JSON array resulting in a single string for the database. At the moment it is not possible to use an array with converters (you can track this feature request).

How to convert Enums correctly

Enums are popular with data objects like entities. When persisting enums, there are a couple of best practices:

• Do not persist the enum’s ordinal or name: Both are unstable, and can easily change the next time you edit your enum definitions.

• Use stable ids: Define a custom property (integer or string) in your enum that is guaranteed to be stable. Use this for your persistence mapping.

• Prepare for the unknown: Define an UNKNOWN enum value. It can serve to handle null or unknown values. This will allow you to handle cases like an old enum value getting removed without crashing your app.

Custom types in queries

QueryBuilder is unaware of custom types. You have to use the primitive DB type for queries.

So for the Role example above you would get users with the role of admin with the query condition .equal(UserProperties.Role, 2).