From 99d6de546c74f0eed230ea8253dda6b85109d2e7 Mon Sep 17 00:00:00 2001
From: Markus Koivisto <markus@vaadin.com>
Date: Fri, 22 Jan 2016 14:55:18 +0200
Subject: Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674
---
 .../jpacontainer/jpacontainer-overview.asciidoc    | 123 +++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 documentation/jpacontainer/jpacontainer-overview.asciidoc

(limited to 'documentation/jpacontainer/jpacontainer-overview.asciidoc')

diff --git a/documentation/jpacontainer/jpacontainer-overview.asciidoc b/documentation/jpacontainer/jpacontainer-overview.asciidoc
new file mode 100644
index 0000000000..a622c0509d
--- /dev/null
+++ b/documentation/jpacontainer/jpacontainer-overview.asciidoc
@@ -0,0 +1,123 @@
+---
+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
+<<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
+
+
+
+
+
-- 
cgit v1.2.3

