|
|
|
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:
This tutorial contains all of the above. Let's take a look.
|
|
|
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.
|
|
|
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:
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.
|
|
|
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).
