18.2. Installing
Prev Chapter 18. Vaadin JPAContainer Next

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.

Vaadin JPAContainer is available for download from the Vaadin Directory. Please see Section 15.2, “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.

Vaadin JPAContainer is available under two licenses: Affero General Public License (AGPL) and Commercial Vaadin Add-on License (CVAL). If your project is compatible with the open-source AGPL, you can use the add-on for free. Otherwise you must acquire a sufficient number of CVAL licenses before the 30-day trial period ends. Vaadin JPAContainer is distributed as a separate installation package for each license.

Use of Vaadin JPAContainer with the CVAL license is included in the Vaadin PRO subscription.

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

README

A readme file describing the package contents.

licensing.txt

General information about licensing of JPAContainer.

license-xxxx-y.y.txt

The full license text for the library.

vaadin-jpacontainer-xxxx-y.y-z.z.z.jar

The actual Vaadin JPAContainer library. The xxxx is the license name and y.y its version number. The final z.z.z is the version number of the Vaadin JPAContainer.

vaadin-jpacontainer-xxxx-y.y-z.z.z-javadoc.jar

JavaDoc documentation 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.

apidocs

A folder containing the JavaDoc API documentation in plain HTML.

jpacontainer-tutorial.pdf

The tutorial in PDF format.

jpacontainer-tutorial

The tutorial in HTML format. The online version of the tutorial is always available at vaadin.com/download/jpacontainer-tutorial/.

jpacontainer-addressbook-demo

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

jpacontainer-demo-z.z.z.war

The basic JPAContainer demo. It is somewhat more extensive than the AddressBook Demo.

The download page in Vaadin Directory gives the dependency declaration needed for retrieving the Vaadin JPAContainer library with Maven. A separate dependency declaration is given for both available licenses for Vaadin JPAContainer.

For the CVAL License: 

<dependency>
   <groupId>com.vaadin.addon</groupId>
   <artifactId>jpacontainer-addon-cval-2.0</artifactId>
   <version>2.0.0</version>
</dependency>

For the AGPL License: 

<dependency>
   <groupId>com.vaadin.addon</groupId>
   <artifactId>jpacontainer-addon-agpl-3.0</artifactId>
   <version>2.0.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 Section 15.5, “Using Add-ons in a Maven Project” for detailed instructions for using a Vaadin add-on with Maven.

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

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.

Optionally, you may need to also install the Vaadin BeanValidation add-on. If you do so, you also need an implementation of the Bean Validation, such as Hibernate Validator.

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.

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">

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 Section 18.4.1, “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.

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"/>

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" />

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>

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.

Prev Up Next
Chapter 18. Vaadin JPAContainer Home 18.3. Defining a Domain Model