Onyx Database Persistence Manager Factory

Embedded Persistence Manager Factory
Create an embedded database and set up a connection.
This guide walks you through how to set up Onyx Database to persist data permanently to your local hard drive or SSD drive.

You can download the code for this example here: OnyxDevTools/onyx-database-samples/embedded-persistence-manager.

Why Use?

An Embedded Persistence Manager Factory is used to configure your PersistenceManager to save data to disk. Onyx Database automatically caches all of your local data. Because of this, you can get extremely high performance for the retrieval of entities. For smaller datasets, the entire dataset is memory mapped. For larger datasets, automatic caching is determined by your off-heap memory allocation and optimized by a built-in intuitive caching algorithm that discards the Least Recently Used (LRU) and Least Frequently Used (LFU) records.

Note: It is best practice to use the factory to create a global singleton instance rather than constructing a new manager each time you use it.

Here is an example of how to use an EmbeddedPersistenceManagerFactory:

  1. Create an instance of a EmbeddedPersistenceManagerFactory.
  2. Set the database credentials.

    This step is optional. If you do not specify a username or password. The credentials will default to admin/admin.

  3. Set the Database Location

    Here you specify the full path to where you want the data to be stored. If the database location does not exist, it will create it for you. Ensure you have file read and write permissions to the target directory. The database file location must contain an .oxd extension.
    Note: In this example the database files are store in a hidden folder.

  4. Set up the database connection

    By initializing the embedded database PersistenceManagerFactory, you will retain a lock so that it cannot be opened by another process.
    Note: In this example no Schema Context is specified, therefore, a DefaultSchemaContext will be created for you.

  5. Get the PersistenceManager from the PersistenceManagerFactory.
  6. Save stuff!

    Now that you have an instance of the PersistenceManager you can use it to save, update, query and delete com.onyxdevtools.entities.

  7. Close the Persistence Manager Factory.

    By default Onyx Database adds a JVM shutdown hook upon the termination of the process. It is always a good idea to manually call close when you are finished with the database connection in order to prevent potential data loss.

  8. Cache Manager Factory