salespoint/doc/background/database.tex

\section{JPA - Java Persistence API}
\label{sec:jpa}
%The persistence layer was one of the biggest problems in Salespoint 2010. We wanted a solution that acknowledges latitudes for persisting objects with relatively low effort.
One of the key features of \salespoint{} is its integrated persistence layer. The goal is to allow data persistence, while minimising programming effort and training period as well as maximising flexibility for framework users.

%Therefore and because of the huge community support, we decided to use the Java Persistence API (JPA). JPA is a Java Programming Language Framework managing relational data in applications. The API itself is defined in the javax.persistence package.
The obvious choice was the Java Persistence API (JPA), a Java framework managing relational data in Java Standard Edition or Enterprise Edition applications. \salespoint{} uses JPA 2.0, developed under JSR 317 and finalised in Dec, 2009 \cite{jpa}.

Additionally to the API itself, which is defined in the \texttt{javax.persistence} package, JPA also consists of \textit{Persistence Entities}, \textit{ORM Metadata} and the \textit{Java Persistence Query Language} (JPQL).

A persistence entity is usually a \textit{Plain Old Java Object} (POJO), which is mapped to a single table in a database.
A row in such a database table corresponds to a specific instance of such an entity.
Relational data between entities (and therefore tables) may be specified in an XML descriptor file or as annotations in Java source code.
\salespoint{} uses annotations to provide object/relational metadata.

Persistence entities may be related to each other by an inheritance hierarchy.
A persistence entity may have a non-persistent superclass.
Fields declared by a non-persistent superclass are not stored in the database if an inheriting entity is persisted.
Three schemes exist to persist entites with an inheritance relationship: \textit{single table}, \textit{join table}, and \textit{table per class}.

The \textit{single table} strategy stores all instances of classes of an inheritance hierarchy in the same table.
The table contains columns for every attribute a persistence entity in the hierarchy declares.
The different types are distinguished by a type discriminator column.
The discriminator value for each persistence entity in an inheritance hierarchy is generated automatically or can be supplied by the user.

The \textit{join table} strategy uses a table for the root persistence entity of the inheritance hierarchy.
Additionally, a table is addded for each persistence entity in the inheritance hierarchy.
In the supplementary tables, a foreign key is used to reference a row in the table of the parent persistence entity.
Each table contains only columns for fields declared by a specific persistence entity in the inheritance hierarchy, but neither for the entities children nor parents.
To reconstruct an object from the database, the different tables have to be joined using this foreign key, thus the name of this strategy.

The \textit{table per class} strategy creates a table for each persistence entity containing all fields of the class, including inherited fields.

The inheritance strategy of an inheritance hierarchy has to be declared at the root persistence entity.
The inheritance stratety may not be changes for a sub-hierarchy, because JPA 2.0 does not require this feature.
JPA 2.0 only requires the \textit{single table} and \textit{join table} strategies to be implemented.
\salespoint{} uses the \textit{single table} strategy exclusively.

The query language JPQL, which is similar to SQL, is used to retrieve entity information from the database.
In contrast to SQL, JPQL queries act on entity objects instead of database tables.
JPA implementations translate a JPQL statement to SQL statements at run time.
It is possible to replace the DBMS while keeping the Java classes.
It is possible to interface directly with the DBMS using \textit{Native Queries}.
\salespoint{} however, uses the \textit{Criteria API} \cite{jpa, eclipselink-javadoc} to facilitate type safe querying.

%Some of the most popular vendors of JPA are Hibernate and EclipseLink. For developing Salespoint 2011 we used JPA 2.0 with EclipseLink without vendor specific functionality. So it should also be possible to use other JPA 2.0 vendors like Hibernate with this framework.
Multiple implementations of JPA 2.0 exist, for example TopLink \cite{toplink} and EclipseLink \cite{eclipselink}.
The open source persistence and ORM framework Hibernate \cite{hibernate} also supports JPA 2.0.
\salespoint{} uses the JPA 2.0 reference implementation, EclipseLink.
No implementation specific code is used in \salespoint{}, therefore it should be possible to interchange EclipseLink with another JPA 2.0 implementation.\footnote{This document will be updated, as soon as another JPA provider is tested with \salespoint{}.}