Installing

Installing

Vaadin JPAContainer can be installed either as an installation package, downloaded from the Vaadin Directory, or as a Maven dependency. You can also create a new JPAContainer-enabled Vaadin project using a Maven archetype.

Downloading the Package

Vaadin JPAContainer is available for download from the Vaadin Directory. Please see “Downloading Add-ons from Vaadin Directory” for basic instructions for downloading from Directory. The download page also gives the dependency declaration needed for retrieving the library with Maven.

JPAContainer is a purely server-side component, so it does not include a widget set that you would need to compile.

Installation Package Content

Once extracted to a local folder, the contents of the installation directory are as follows:

README

A readme file describing the package contents.

LICENSE

The full license text for the library.

vaadin-jpacontainer-3.x.x.jar

The actual Vaadin JPAContainer library.

vaadin-jpacontainer-3.x.x-sources.jar

Source JAR for the library. You can use it for example in Eclipse by associating the JavaDoc JAR with the JPAContainer JAR in the build path settings of your project.

jpacontainer-tutorial.pdf

The tutorial in PDF format.

jpacontainer-tutorial-html

The tutorial in HTML format.

jpacontainer-addressbook-demo

The JPAContainer AddressBook Demo project covered in this tutorial. You can compile and package the application as a WAR with “ mvnpackage” or launch it in the Jetty web browser with “ mvn jetty:run”. You can also import the demo project in Eclipse.

Downloading with Maven

The download page in Vaadin Directory gives the dependency declaration needed for retrieving the Vaadin JPAContainer library with Maven.

<dependency>
   <groupId>com.vaadin.addon</groupId>
   <artifactId>jpacontainer</artifactId>
   <version>3.2.0</version>
</dependency>

Use the LATEST version tag to automatically download the latest stable release or use a specific version number as done above.

See “Using Add-ons in a Maven Project” for detailed instructions for using a Vaadin add-on with Maven.

Using the Maven Archetype

If you wish to create a new JPAContainer-enabled Vaadin project with Maven, you can use the vaadin-archetype-jpacontainer archetype. Please see “Using Vaadin with Maven” for details on creating a Vaadin project with a Maven archetype.

Including Libraries in Your Project

The Vaadin JPAContainer JAR must be included in the library folder of the web application. It is located in WEB-INF/lib path in a web application. In a normal Eclipse web projects the path is WebContent/WEB-INF/lib. In Maven projects the JARs are automatically included in the folder, as long as the dependencies are defined correctly.

You will need the following JARs:

Vaadin Framework Library
Vaadin JPAContainer
Java Persistence API 2.0 (javax.persistence package)
JPA implementation (EclipseLink, Hibernate, …)
Database driver or embedded engine (H2, HSQLDB, MySQL, PostgreSQL, …)

If you use Eclipse, the Vaadin Framework library is automatically downloaded and updated by the Vaadin Plugin for Eclipse.

To use bean validation, you need an implementation of the Bean Validation, such as Hibernate Validator.//TODO elaborate

Persistence Configuration

Persistence configuration is done in a persistence.xml file. In a regular Eclipse project, it should be located in WebContent/WEB-INF/classes/META-INF. In a Maven project, it should be in src/main/resources/META-INF. The configuration includes the following:

The persistence unit
The persistence provider
The database driver and connection
Logging

The persistence.xml file is packaged as WEB-INF/classes/META-INF/persistence.xml in the WAR. This is done automatically in a Maven build at the package phase.

Persistence XML Schema

The beginning of a persistence.xml file defines the used schema and namespaces:

<?xml version="1.0" encoding="UTF-8"?>
<persistence
    xmlns="http://java.sun.com/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
      http://java.sun.com/xml/ns/persistence
      http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
    version="2.0">

Defining the Persistence Unit

The root element of the persistence definition is persistence-unit. The name of the persistence unit is needed for creating JPAContainer instances from a JPAContainerFactory, as described in “Creating JPAContainer with JPAContainerFactory” or when creating a JPA entity manager.

<persistence-unit name="addressbook">

Persistence provider is the JPA provider implementation used. For example, the JPAContainer AddressBook demo uses the EclipseLink JPA, which is defined as follows:

<provider>
    org.eclipse.persistence.jpa.PersistenceProvider
</provider>

The persistent classes need to be listed with a <class> element. Alternatively, you can allow including unlisted classes for persistence by overriding the exclude-unlisted-classes default as follows:

<exclude-unlisted-classes>false</exclude-unlisted-classes>

JPA provider specific parameters are given under the properties element.

<properties>
   ...

In the following section we give parameters for the EclipseLink JPA and H2 database used in the JPAContainer AddressBook Demo. Please refer to the documentation of the JPA provider you use for a complete reference of parameters.

Database Connection

EclipseLink allows using JDBC for database connection. For example, if we use the the H2 database, we define its driver here as follows:

<property name="eclipselink.jdbc.platform"
 value="org.eclipse.persistence.platform.database.H2Platform"/>
<property name="eclipselink.jdbc.driver"
          value="org.h2.Driver" />

Database connection is specified with a URL. For example, using an embedded H2 database stored in the home directory it would be as follows:

<property name="eclipselink.jdbc.url"
          value="jdbc:h2:~/my-app-h2db"/>

A hint: when using an embedded H2 database while developing a Vaadin application in Eclipse, you may want to add ;FILE_LOCK=NO to the URL to avoid locking issues when redeploying.

We can just use the default user name and password for the H2 database:

<property name="eclipselink.jdbc.user" value="sa"/>
<property name="eclipselink.jdbc.password" value="sa"/>

Logging Configuration

JPA implementations as well as database engines like to produce logs and they should be configured in the persistence configuration. For example, if using EclipseLink JPA, you can get log that includes all SQL statements with the FINE logging level:

<property name="eclipselink.logging.level"
          value="FINE" />

Other Settings

The rest is some Data Definition Language settings for EclipseLink. During development, when we use generated example data, we want EclipseLink to drop tables before trying to create them. In production environments, you should use create-tables.

<property name="eclipselink.ddl-generation"
          value="drop-and-create-tables" />

And there is no need to generate SQL files, just execute them directly to the database.

<property name="eclipselink.ddl-generation.output-mode"
          value="database"/>
      </properties>
 </persistence-unit>
</persistence>

Troubleshooting

Below are some typical errors that you might get when using JPA. These are not specific to JPAContainer.

javax.persistence.PersistenceException: No Persistence provider for EntityManager

The most typical cases for this error are that the persistence unit name is wrong in the source code or in the persistence.xml file, or that the persistence.xml is at a wrong place or has some other problem. Make sure that the persistence unit name matches and the persistence.xml is in WEB-INF/classes/META-INF folder in the deployment.

java.lang.IllegalArgumentException: The class is not an entity

The class is missing from the set of persistent entities. If the persistence.xml does not have exclude-unlisted-classes defined as false, the persistent entity classes should be listed with <class> elements.