FairCom — FairCom DB API Java Persistence API (JPA) Quick Start Guide

This book contains tutorials for the FairCom DB API JPA API for Java. In these simple steps and about 15 minutes, you’ll be navigating your data:

Install and start up the FairCom Database Engine. See Installing FairCom Products.
Optionally read the overview Introduction to FairCom DB API JPA.
Build and Run the tutorials as explained in Getting Started with FairCom DB API JPA.

Tip: To view, edit, and run the source code for the tutorials, you can go directly into the <faircom>\drivers\java.jpa.nav\tutorials folder that is installed with the product. Each tutorial has been thoroughly tested on each operating system, interpreter, and compiler to ensure you have an excellent experience.

Resources

c-tree Database API for Other Languages

FairCom allows you to use NAV APIs with the language of your choice:

Note: FairCom supports all actively-supported LTS versions of the Oracle JDK, and the most recent release (non-beta) version of Oracle OpenJDK.

Introduction to FairCom DB API JPA

The FairCom FairCom DB API Java Persistence API, commonly referred to as the FairCom DB API JPA, provides Java developers a unique record-oriented, non-SQL, Java framework to persist data using the FairCom Database Engine.

Most JPA drivers are built on SQL APIs, but this driver is different in that it avoids the SQL API layers and uses FairCom DB API API for increased performance.

FairCom also provides a JPA driver that uses the SQL API; see the FairCom DB Java Hibernate ReadMe.

Different open source projects exist that implement the JPA specification. Popular projects include Hibernate and EclipseLink. This driver was developed using EclipseLink.

The Java Persistence API (JPA) and FairCom DB

FairCom provides two ways to integrate with the Java Persistence API. First it provides a dialect for Hibernate. Hibernate is the original open source invention that led to the JPA standard. Second it provides a JCA adapter for EclipseLink. EclipseLink is another open source implementation of the JPA standard. EclipseLink supports NoSQL data access through the JavaEE Connector Architecture. FairCom has developed a JCA adapter for EclipseLink that allows JPA programmers to communicate with FairCom DB using the JTDB API thus circumnavigating the SQL layer. This gives the EclipseLink integration a significant speed advantage.

A typical FairCom DB download comes with many tutorials for our different programming language drivers. You can find the tutorial files for the EclipseLink integration in the drivers/java.jpa.nav/tutorials folder.

This tutorial uses the popular build system Gradle to build and execute the tutorial.

Note: This tutorial requires Java 8, 9, 11, 15, or 16.

You will not need to install Gradle. The tutorial contains a Gradle bootstrap binary that takes care of everything needed to build and run the tutorial. You will need Internet access, however, so it can download all needed dependencies.

A typical JPA program needs the following:

a file called META-INF/persistence.xml
a Java class with an @Entity annotation.
a Java program that uses a javax.persistence.EntityManager to persist entities.

This tutorial contains all of the above. Let's take a look.

persistence.xml

First, let's look at drivers/java.jpa.nav/tutorials/src/main/resources/META-INF/persistence.xml

The file contains information on how EclipseLink is supposed to connect to FairCom DB. The information is written in XML syntax.

Here is a copy of the information in an easy-to-read syntax:

persistence:
  persistence-unit:
    provider: org.eclipse.persistence.jpa.PersistenceProvider
    class: Email
    exclude-unlisted-classes: 'true'
    properties:
      property:
        - _name: eclipselink.target-database
          _value: com.faircom.persistence.eclipselink.CtreePlatform
        - _name: eclipselink.nosql.connection-spec
          _value: com.faircom.persistence.eclipselink.CtreeConnectionSpec
        - _name: eclipselink.nosql.property.ctree.servername
          _value: FAIRCOMS
        - _name: eclipselink.nosql.property.ctree.serveraddress
          _value: 127.0.0.1
        - _name: eclipselink.nosql.property.ctree.db
          _value: ctreeSQL
        - _name: eclipselink.nosql.property.ctree.user
          _value: ADMIN
        - _name: eclipselink.nosql.property.ctree.pw
          _value: ADMIN
        - _name: eclipselink.logging.level
          _value: INFO
        - _name: ddl-generation
          _value: create
    _name: TestJPAPU

As you can see, the file defines servername, serveraddress, db, user, password, and loglevel.

It also defines ddl-generation. Setting ddl-generation to 'create' tells EclipseLink to create missing tables.

Entity Classes

Taking a closer look at drivers/java.jpa.nav/tutorials/src/main/java/Email.java, we see some standard javax.persistence imports. Those all come from the JPA standard. But we can also see some org.eclipse.persistence.nosql.annotations. Those come from the EclipseLink library and, more specifically, they come from the EclipseLink NoSQL support. FairCom uses those to circumnavigate the SQL layer. We can see three annotations:

DataFormatType
Field
NoSql

The NoSql annotation allows us to specify the DataFormatType to be MAPPED. This means that object data is decomposed into a Map of key/value pairs. The Field annotation is used to specify the name of the field in the FairCom DB table. These are both necessary settings for the FairCom JCA adapter to function properly. So be sure to set them on all your entity classes and fields.

Other than that, we can see a normal JPA Entity class. In the case of the tutorial, the class is supposed to represent an email. Fields include: sender, subject, textpreview and received.

Using the Entity Class

To use the entity class in the context of the Java Persistence API we need to use a javax.persistence.EntityManager.

A demo of how this can be done can be found in drivers/java.jpa.nav/tutorials/src/main/java/Main.java.

The code basically consists of this:

EntityManagerFactory emf = Persistence.createEntityManagerFactory("TestJPAPU");
EntityManager em = emf.createEntityManager();
Email email = new Email();
email.setSubject("Subject");
email.setSender("Sender");
email.setReceived(new Date());
em.getTransaction().begin();
em.persist(email);
em.getTransaction().commit();
System.out.println("ID: " + email.getId());

In the first line we create a new EntityManagerFactory. Note that we use the same name we used in the persistence.xml. From the EntityManagerFactory we of course get an EntityManager. We use the EntityManager to begin a transaction and to persist a new instance of our Email entity class. Then we commit the transaction. Finally we print out the new ID of the Email entity class. This ID was created by FairCom DB on insert of the new record and is set by EclipseLink on the entity class instance.

Note that it is not always necessary to create an EntityManagerFactory. In some Java EE environments an EntityManager is provided for you (for example in GlassFish).

Getting Started with FairCom DB API JPA

This driver was developed using EclipseLink version 2.6.1 and Java version 8.

Inside the driver folder you will find the following files and folders:

FairComCtreeDB.jar - The standard FairCom DB API Java navigational API.
libmtclijni64.so or mtclijni64.dll - a client-side library needed by FairCom DB API Java.
FairComCtreeDB_JPA.jar - The EclipseLink JPA driver.
tutorials - The folder with an example project using the Gradle build system.

You do not need to install Gradle for the tutorial to work. But you do need a working internet connection, because the tutorial build script will download all the necessary files for it to work.

Be sure you have Java 8, 9, 11, 15, or 16 installed and then access the tutorials folder using a command-line interface. On Windows, you can use the “Apps & Features” control to list the installed programs, and it will show which Java version you have installed.

Execute one of the following based on which operating system you are using:

Linux:	`> make build; make run`
Windows:	`> BuildTutorials.bat`

The first time you run the tutorial, the program will create an ‘Email’ table, and you will see output like this (in addition to the output that is emitted by Gradle):

creating table: Email
creating field: id
creating field: sender
creating field: subject
creating field: textpreview
creating field: hash
creating field: tags
creating field: archived
creating field: received
creating field: created

Subsequent runs of the tutorial will not create the ‘Email’ table, because it already exists, so the above text will not be emitted.

Adjusting the Connection Information

The connection information is stored in the persistence.xml file. It can be found here in the following location:

drivers\java.jpa.nav\tutorials\src\main\resources\META-INF\persistence.xml

How to Start Your Own Project

The best way to start your own project is to copy the tutorials folder and rename it. Then follow these steps to create your project:

Rename the project name in the settings.gradle file.
Copy the FairCom DB API Java and JPA driver files to a lib subfolder.
Modify the build.gradle file and adjust the java.library.path systemProperty to point to the location of the native libraries.
Depending on your environment, you might need to adapt the persistence.xml file.
It is a good idea to rename the persistence-unit from TestJPAPU to something resembling your environment or project. If you do so, remember to also change this in the call to createEntityManagerFactory if you don't use a Java EE application server.
Create one or more entity classes to persist your application data. Remember to annotate them with: @NoSql(dataFormat = DataFormatType.MAPPED) and each field with @Field(name = "yourname")
Add each entity class name to the persistence.xml file.
Finally, create or use the EntityManager in a real program to persist and load your application data.

Contact FairCom if you have any questions about this process.

Troubleshooting

org.eclipse.persistence.exceptions.PersistenceUnitLoadingException

This error means you are running the wrong version of the Java JRE. Install Java version 8.x and try again.

java.lang.NoClassDefFoundError: Could not initialize class org.codehaus.groovy.vmplugin.v7.Java7

This error means you are running the wrong version of the Java JDK. Install Java version 8.x and try again.

Could not initialize class org.codehaus.groovy.runtime.InvokerHelper

This error means you are running the wrong version of the Java JDK. Install Java version 8.x and try again.

Could not initialize class org.codehaus.groovy.reflection.ReflectionCache

This error means you are running the wrong version of the Java JDK. Install Java version 8.x and try again.

java.lang.UnsatisfiedLinkError: no mtclijni64 in java.library.path

This error means that the FairCom DB API Java driver could not find the client-side library:

On Windows the client-side library needs to be accessible in one of the folders of the path. Adjust the java.library.path systemProperty in the build.gradle file or adjust the path system variable or copy the client side library into a folder on the path.

On Linux there is an easy way to fix this. Issue the following command:

> export LD_LIBRARY_PATH=<path-to-client-side-library>

Note that it sometimes is enough to simply copy the client-side library into the current working directory.

javax.resource.ResourceException: c-tree logon error

This error means that the driver could not reach the server:

javax.resource.ResourceException: c-tree logon error

The most common cause of this runtime error is the FairCom Database Engine is not running on your machine. The most likely cause is that the c-tree evaluation license times out after 3 hours and shuts down the server. The solution is to restart the server; see Starting the FairCom Database Engine.

Make sure the server is running and not blocked by the firewall.

Make sure the connection information in persistence.xml is correct.

ResourceException: Can't connect to database

The following error means that the driver could reach the server but the database defined in persistence.xml does not exist.

To fix this issue, either create the database for example using the FairCom SQL Explorer or adjust the database name in persistence.xml to match an existing database.

FairCom DB API Java Persistence API (JPA) Quick Start Guide

Introduction to FairCom DB API JPA

The Java Persistence API (JPA) and FairCom DB

persistence.xml

Entity Classes

Using the Entity Class

Getting Started with FairCom DB API JPA

Adjusting the Connection Information

How to Start Your Own Project

Troubleshooting

Was this article helpful?

Related Articles

JDBC transaction processing tutorial

JDBC relationships tutorial

Basic JDBC driver operations