Using EclipseLink with PostgreSQL

1. Introduction

EclipseLink was announced in 2008 as the JPA 2.0 implementation from the Eclipse Foundation. It is based on the TopLink project from which then Oracle contributed code to the EclipseLink project. The project delivers an open source runtime framework supporting the Java Persistence API standards. The EclipseLink project provides a proven, commercial quality persistence solution that can be used in both Java SE and Java EE applications.

EclipseLink is open source and is distributed under the Eclipse Public License.

2. Implementation Details

Like Hibernate, EclipseLink is also fully JPA 2.0 compliant. This makes the implementation details quite similar to those already described in a preceding Hibernate blog.

For the illustration below, we will continue using the ‘largecities’ example with table structure:

 postgres=# \d largecities

         Table "public.largecities"

 Column |          Type          | Modifiers 

--------+------------------------+-----------

 rank   | integer                | not null

 name   | character varying(255) | 

Indexes:

    "largecities_pkey" PRIMARY KEY, btree (rank)

2.1 Creating an Entity

You can create the entity using JPA’s standard @Entity and @Id (and other) annotations:

import javax.persistence.Entity;
import javax.persistence.Id;

@Entity
public class LargeCities {
    @Id
    private int rank;
    private String name;

    public int getRank() {
        return rank;
 }
    public String getName() {
        return name;
    }
    public void setRank(int rank) {
        this.rank = rank;
    }
    public void setName(String name) {
        this.name = name;
    }
}

2.2 Creating the Configuration XML

EclipseLink’s configuration XML file goes by the name of persistence.xml and should be placed under the META-INF folder at the root of the persistence unit or on the classpath. A sample XML is given below:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0"
    xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
    <persistence-unit name="MyEclipseLinkExample" transaction-type="RESOURCE_LOCAL">
        
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <class>org.secondquadrant.javabook.eclipselink.LargeCities</class>
        <properties>
            <property name="javax.persistence.jdbc.driver" value="org.postgresql.Driver" />
            <property name="javax.persistence.jdbc.url" value="jdbc:postgresql://localhost:5432/postgres" />
            <property name="javax.persistence.jdbc.user" value="postgres" />
            <property name="javax.persistence.jdbc.password" value="" />
        </properties>
    </persistence-unit>
</persistence>

Pretty much all the element names are self-explanatory. The one thing to be especially careful about is the persistence-unit ‘name’ property. This needs to correspond to your main Java class.

2.3 Accessing the Database

The steps needed in order to access the database using EclipseLink are:

1. Create an entity manager factory using the persistence-unit name specified in the project’s persistence.xml file.
2. Create an entity manager using the entity manager factory object.
3. Access the database using this entity manager.

Sample code for a simple read operation is as follows:

public static void main(String[] args) {

    try {
            EntityManagerFactory emf = Persistence.createEntityManagerFactory("MyEclipseLinkExample");
            EntityManager em = emf.createEntityManager(); 
     
        List<LargeCities> cities = em.createQuery("SELECT l FROM LargeCities l", LargeCities.class).getResultList(); 

        for (LargeCities c : cities)
            System.out.println(c.getRank() + " " + c.getName());

    } catch (Exception e) {
        System.out.println(e.getMessage()); 
    }
}

Besides the steps mentioned above, the additional thing of significance in this code is how the query is created. Notice the usage of ‘LargeCities’ rather than ‘largecities’, as is the name of the table we created. This is because EclipseLink is looking at our entity and then mapping it to the database based on persistence.xml rather than looking directly at the database. Also, an identification variable ‘l’ is assigned to the LargeCities entity. The same ‘l’ is then SELECTed to assign to the LargeCities List variable to get our resultset. This syntax is different from the typical SQL syntax used directly against databases.

3. Other Features of EclipseLink

EclipseLink is much more than a simple JPA implementation. Amongst others, it also implements JAXB, JCA, & SDO. One of the most interesting features, however, is its ability to talk to NoSQL databases.

3.1 NoSQL

NoSQL databases have surged in popularity due to the tremendous demand for horizontal scalability for clusters of servers. These databases do not conform to the tabular relations maintained by traditional Relational Database Systems (RDMS) like PostgreSQL and maintain different mechanics for storage and retrieval of data.

As of version 2.4, EclipseLink has support for the NoSQL databases MongoDB & Oracle NoSQL. This allows you to use the JPA API & annotations against these NoSQL databases exactly like you would use them against a standard RDBMS. In addition to the standard JPA functionality, EclipseLink also provides some NoSQL-specific annotations, thus providing more flexibility with these specialized databases.

3.2 Java EE Connector Architecture (JCA)

JCA is a generic architecture for connecting application servers to enterprise information systems in legacy models. It is different from JDBC as the latter is designed to connect Java EE applications to databases.

EclipseLink’s NoSQL support described in the previous section is based on its JCA functionality. Even though only MongoDB and Oracle NoSQL are supported at the moment, EclipseLink’s NoSQL functionality can be extended with the right JCA adapter and a new EclipseLink EISPlatform class.

3.3 Java Architecture for XML Binding (JAXB)

JAXB is to Java & XML what JPA is to Java & databases. Essentially, it allows developers to map their POJOs directly to XML files.

EclipseLink’s implementation of JAXB allows for binding of Java objects to both XML and JSON. The mapping information can be provided either as annotations or in an XML mapping document.

3.4 Service Data Objects (SDO)

Very relevant in today’s world of big data that brings in a lot of diversity, SDO allows a variety of data to be accessed in pretty much a uniform way.

EclipseLink’s MOXy implements the SDO standard, allowing programmers to bind their POJOs by providing mapping information either as annotations or in an XML document. MOXy can also be used in conjunction with the JPA implementation to access traditional relational databases.

3.5 Database Web Services (DBWS)

The DBWS component of EclipseLink allows programmers to access the database via a web service using the persistence services provided by the solution. The inbuilt DBWS builder has the ability to automatically generate config files that enable the usage of persistence and web services in parallel. As you can imagine, this makes EclipseLink a very powerful tool to use for database access over the web independent of platform.