Embedded Persistence Manager Factory

This tutorial will guide you through setting up an embedded Onyx Database, configuring the connection using the Embedded Persistence Manager Factory, and performing basic operations.

Note: Cloud vs. Open Source Implementation

This guide focuses on the Onyx Open Source Database. In contrast, the Onyx Cloud Databaseoffers managed services where persistence managers are encapsulated, eliminating the need for manual configuration. For more details on the cloud implementation, refer to our comprehensiveUser Guide for Onyx Cloud Database.

The cloud database provides additional features such as enhanced security, scalability, and automated backups.

Download Example Code on GitHub

Why Use Embedded Persistence Manager Factory?

An Embedded Persistence Manager Factory is essential for configuring your PersistenceManager to persist data permanently to your local hard drive or SSD. Onyx Database automatically caches all your local data, ensuring high performance for data retrieval. 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.

Setup and Configuration Steps

Follow the steps below to set up your project with the Embedded Persistence Manager Factory.

1

Step 1: Add Onyx Dependency to Gradle

To start using the Onyx Open Source Database, you need to add it as a dependency to your project. Depending on whether you're using Kotlin or Groovy for your Gradle build scripts, choose the appropriate snippet below and add it to your build.gradle.kts or build.gradle file.
1repositories {
2    mavenCentral()
3    maven {
4        url = uri("https://maven.pkg.github.com/OnyxDevTools/onyx-database-parent")
5        credentials {
6            username = "github_username"
7            password = "github_access_token"
8        }
9    }
10}
11
12dependencies {
13    implementation("com.onyxdevtools:onyx-database:3.4.4") // Embedded Database
14    implementation("com.onyxdevtools:onyx-remote-database:3.4.4") // Remote Database Server
15    implementation("com.onyxdevtools:onyx-remote-driver:3.4.4") // Remote Database Client
16}
2

Step 2: Create an Instance of EmbeddedPersistenceManagerFactory

Initialize the factory with the desired database path. This path specifies where the database files will be stored. If the directory does not exist, it will be created automatically.
1import com.onyx.persistence.EmbeddedPersistenceManagerFactory
2import java.io.File
3
4val pathToOnyxDB = System.getProperty("user.home") +
5        File.separator + ".onyxdb" +
6        File.separator + "sandbox" +
7        File.separator + "embedded-db.oxd"
8
9val factory = EmbeddedPersistenceManagerFactory(pathToOnyxDB)
10factory.setCredentials("onyx-remote", "SavingDataIsFun!")
11factory.initialize()
12
13val manager = factory.persistenceManager
3

Step 3: Set the Database Credentials

This step is optional. If you do not specify a username or password, the credentials will default to admin for both the username and password.
4

Step 4: Set the Database Location

Specify the full path to where you want the data to be stored. Ensure you have file read and write permissions to the target directory.
Note: In this example, the database files are stored in a hidden folder.
5

Step 5: Set Up the Database Connection

By initializing the embedded database PersistenceManagerFactory, you 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.
6

Step 6: Get the PersistenceManager from the PersistenceManagerFactory

The PersistenceManager instance is used to perform CRUD operations on your entities.
7

Step 7: Save Data Using the PersistenceManager

With the PersistenceManager, you can save, update, query, and delete entities.
8

Step 8: Close the Persistence Manager Factory

It's a good practice to manually close the factory when you're finished to prevent potential data loss. Onyx Database adds a JVM shutdown hook upon termination of the process, but closing manually ensures immediate release of resources.
1factory.close()

Troubleshooting

  • Invalid username or password: Verify that the credentials provided in your configuration are correct.
  • Invalid configuration: Check for issues such as incorrect encryption settings or a mismatched encryption key.
  • Invalid database location or contents: Ensure the database path is correct and the contents are valid.
  • Dependency not found: Ensure that you've added the correct repository to your build tool configuration and that your GitHub credentials are valid.

Next Steps

Congratulations! You've successfully set up an embedded Onyx Database. To further enhance your knowledge, proceed to the next tutorials: