diff options
| author | Markus Koivisto <markus@vaadin.com> | 2016-01-22 14:55:18 +0200 |
|---|---|---|
| committer | Markus Koivisto <markus@vaadin.com> | 2016-01-22 14:55:18 +0200 |
| commit | 99d6de546c74f0eed230ea8253dda6b85109d2e7 (patch) | |
| tree | 10fc21c557566fe3241e6e13499df18d80f8dcb2 /documentation/jpacontainer/jpacontainer-overview.asciidoc | |
| parent | 610736d9f373d4b37fd39ff8f90aabd13eab7926 (diff) | |
| download | vaadin-framework-99d6de546c74f0eed230ea8253dda6b85109d2e7.tar.gz vaadin-framework-99d6de546c74f0eed230ea8253dda6b85109d2e7.zip | |
Add documentation to master branch
Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674
Diffstat (limited to 'documentation/jpacontainer/jpacontainer-overview.asciidoc')
| -rw-r--r-- | documentation/jpacontainer/jpacontainer-overview.asciidoc | 123 |
1 files changed, 123 insertions, 0 deletions
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 + + + + + |