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

Why Use?

A Remote Persistence Manager Factory is used to connect to a scalable high throughput database. The Remote database is used to store data in a centralized location and provide access to that data among clients.

Much like the embedded database the remote server automatically caches high frequency data in order to provide great performance. Onyx Remote Database Server provides a low latency server that is capable of providing high frequency and fault-tolerant network IO.

Using a proprietary serialization mechanism reduces the network bandwidth and requires less processing which allows Onyx to provide superior throughput.

Project 1: The Data Model

1. Stage the data model as a separate project that contains all of your entities.

   By declaring your entities in a separate project you only have to maintain one model and you can add the data model as a dependency for both the server and the client

   
   
   Notes:

   A complete pom.xml can be seen here

   Make sure to include onyx-database.jar as a dependency so that you can use Onyx Database annotations
2. Declare an entity
   
   
3. Install the project so that it is available as dependency in your m2 directory
4. Create the server project...

Project 2: The Server

1. Create a jar project that will be launched as a database server
   
   Notes:

   A complete pom.xml can be seen here

   Make sure to include onyx-remote-database.jar and the data-model.jar you created earlier as dependences.

   You do not need to include onyx-database.jar; it will automatically be include because it is a transitive dependency of onyx-remote-database.jar
2. Use the maven-shaded-plugin to bundle all dependencies and create a Manifest file to specify a mainClass when executing the jar
   
3. Create a main method within a mainClass of your liking

   The main method will configure and create a running instance of the database server.

   Notes:

   Specify a port to listen to

   Specify a local path to store your binary data

   It's a pretty good idea to set security credentials. If you do not they will default to: admin/admin

   Start the database server. This will initiate a running background thread, which your server application can join
4. Now you can start you database server

   Navigate to the queryRootDirectory directory of the database server project, and run the following command:
5. Create a client...

Project 3: The Client

1. Create a client jar project that will connect to the an external database server
   
   Notes:

   A complete pom.xml can be seen here

   Make sure to include onyx-remote-driver.jar and the data-model.jar you created earlier as dependences.
2. Set up a connection by creating an instance of a RemotePersistenceManagerFactory.
   
   Notes:

   Make sure to use a RemotePersistenceManagerFactory

   The RemotePersistenceManagerFactory provides 2 Persistence Managers. Use getSocketPersistenceManger() for optimized performance as it reduces network latency.

   Set the database credentials to match the server project configuration

   With a remote database, you specify a url for the database location rather than a file location.

   A direct socket connection to Onyx Database uses the onx schema
3. Save stuff!

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

4. Close the connection using 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.

5. Restful Web Persistence Manager Factory