--- title: Overview order: 1 layout: page --- [[jpacontainer.overview]] = Overview 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 <>. 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]] .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 <> 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 <>. 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 <>. [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