vaadin-framework/documentation/jpacontainer/jpacontainer-overview.asciidoc

---
title: Overview
order: 1
layout: page
---

[[jpacontainer.overview]]
= Overview

NOTE: Using JPAContainer is no longer recommended.
While it works for simple data models, it is not as easy to use as it should be.
It also has architectural weaknesses and performance issues that cause problems in building more complex applications.
Instead, we recommend using JPA directly, while hiding it from your UI logic behind a DAO or service class.
In UI code, you should mainly handle beans and collections of beans, bound to a [classname]#BeanItemContainer#. You should also note the https://vaadin.com/directory#!addon/viritin[Viritin] add-on, which provides data binding features that help with JPA.

Vaadin JPAContainer add-on makes it possible to bind user interface components
to a database easily using the Java Persistence API (JPA). It is an
implementation of the [interfacename]#Container# interface described in
<<dummy/../../../framework/datamodel/datamodel-container#datamodel.container,"Collecting
Items in Containers">>. It supports a typical three-layer application
architecture with an intermediate __domain model__ between the user interface
and the data access layer.

[[figure.jpacontainer.overview.architecture]]
.Three-Layer Architecture Using JPAContainer And JPA
image::img/three-layer-architecture-hi.png[]

The role of Java Persistence API is to handle persisting the domain model in the
database. The database is typically a relational database. Vaadin JPAContainer
binds the user interface components to the domain model and handles database
access with JPA transparently.

JPA is really just an API definition and has many alternative implementations.
Vaadin JPAContainer supports especially EclipseLink, which is the reference
implementation of JPA, and Hibernate. Any other compliant implementation should
work just as well. The architecture of an application using JPAContainer is
shown in <<figure.jpacontainer.overview.detailed-architecture>>.

[[figure.jpacontainer.overview.detailed-architecture]]
.JPAContainer Architecture
image::img/detailed-architecture-hi.png[]

Vaadin JPAContainer also plays together with the Vaadin support for Java Bean
Validation (JSR 303).

[[jpacontainer.overview.jpa]]
== Java Persistence API

Java Persistence API (JPA) is an API for object-relational mapping (ORM) of Java
objects to a relational database. In JPA and entity-relationship modeling in
general, a Java class is considered an __entity__. Class (or entity) instances
correspond with a row in a database table and member variables of a class with
columns. Entities can also have relationships with other entities.

The object-relational mapping is illustrated in
<<figure.jpacontainer.overview.jpa.orm>> with two entities with a one-to-many
relationship.

[[figure.jpacontainer.overview.jpa.orm]]
.Object-Relational Mapping
image::img/jpa-mapping-graphic-hi.png[]

The entity relationships are declared with metadata. With Vaadin JPAContainer,
you provide the metadata with annotations in the entity classes. The JPA
implementation uses reflection to read the annotations and defines a database
model automatically from the class definitions. Definition of the domain model
and the annotations are described in
<<dummy/../../../framework/jpacontainer/jpacontainer-domain-model#jpacontainer.domain-model.annotation,"Persistence
Metadata">>.

The main interface in JPA is the [interfacename]#EntityManager#, which allows
making different kinds of queries either with the Java Persistence Query
Language (JPQL), native SQL, or the Criteria API in JPA 2.0. You can always use
the interface directly as well, using Vaadin JPAContainer only for binding the
data to the user interface.

Vaadin JPAContainer supports JPA 2.0 (JSR 317). It is available under the Apache
License 2.0.


[[jpacontainer.overview.concepts]]
== JPAContainer Concepts

The [classname]#JPAContainer# is an implementation of the Vaadin
[interfacename]#Container# interface that you can bind to user interface
components such as [classname]#Table#, [classname]#ComboBox#, etc.

The data access to the persistent entities is handled with a __entity
provider__, as defined in the [interfacename]#EntityProvider# interface.
JPAContainer provides a number of different entity providers for different use
cases and optimizations. The built-in providers are described in
<<dummy/../../../framework/jpacontainer/jpacontainer-entityprovider#jpacontainer.entityprovider,"Entity
Providers">>.

[classname]#JPAContainer# is by default __unbuffered__, so that any entity
property changes are written immediately to the database when you call
[methodname]#setValue()# for a property, or when a user edits a bound field. A
container can be set as __buffered__, so that changes are written on calling
[methodname]#commit()#. Buffering can be done both at item level, such as when
updating item property values, or at container level, such as when adding or
deleting items. Only __batchable__ containers, that is, containers with a
batchable entity provider, can be buffered. Note that buffering is recommended
for situations where two users could update the same entity simultaneously, and
when this would be a problem. In an unbuffered container, the entity is
refreshed before writing an update, so the last write wins and a conflicting
simultaneous update written before it is lost. A buffered container throws an
[classname]#OptimisticLockException# when two users edit the same item (an
unbuffered container never throws it), thereby allowing to handle the situation
with application logic.


[[jpacontainer.overview.documentation]]
== Documentation and Support

In addition to this chapter in the book, the installation package includes the
following documentation about JPAContainer:

* API Documentation

* JPAContainer Tutorial

* JPAContainer AddressBook Demo

* JPAContainer Demo