Onyx Database: Saving an Entity Tutorial

You can download the code for this example here:

OnyxDevTools/onyx-database-samples/persisting-data/ ... SavingAnEntityExample.java.

Persisting data is the heart of any database or caching mechanism. Onyx Database can efficiently persist data in a few different ways either by saving an entity, batch saving operations, or cascading through a relationship. This tutorial guides you through how to declare an entity and persist it.

  1. Declare an entity.

    All entities must implement IManagedEntity or extend the abstract ManagedEntity class.
    Below illustrates how to use the @Attribute annotation to declare fields as persistable.

    Notes:
    When annotating the attributes you have the option to specify whether the attribute is nullable. Nullable only applies to mutable objects. Primitive typed attributes cannot be null.
    All non transient fields have the @Attribute annotation.
    Only class properties can be annotated. Getters and Setters are ignored.
    An attribute can also specify the max size using the size parameter. Max size only applies to Strings
    When your entity implements Comparable<Person> it will automatically be sorted based on your compareTo logic when being retrieved as a child collection of another entity.
  2. Make sure to declare a primary key with the @Identifier annotation.

    The @Identifier can be any the following supported data types:

    String
    Integer
    int
    Long
    long
    Double
    double
    Date

    If the data type is numeric, you can choose to auto increment the identifier using Onyx Database's built-in sequencer.
    Generator types include IdentifierGenerator.SEQUENCE or by default IdentifierGenerator.NONE.
    You can only specify one attribute as the Identifier.

    Notes:
    You must annotate the primary key property with @Identifier and @Attribute annotation.
    The identifier as well as the attribute access modifier can be private, protected, or public.
  3. Get an instance of an Entity Persistence Manager via the Persistence Manager Factory
  4. Create an instance of the entity you declared in step 1 and set all applicable attributes.

    For more information on Persistence Managers, see: Persistence Manager Factories

  5. Invoke the PersistenceManager#saveEntity method using the Persistence Manager.
    Notes:
    Onyx does not differentiate between updating or inserting managed entities. If an entity with a matching primary key already exists, Onyx Database will assume you are updating the entity specified and overwrite the existing record.
  6. Verify that the instance has been persisted using the PersistenceManager#find method.
  7. Batch Saving