Installing

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

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

    See 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 “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, …​)

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

    Persistence XML Schema

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

    2. <persistence
    3.     xmlns="http://java.sun.com/xml/ns/persistence"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xsi:schemaLocation="
    6.       http://java.sun.com/xml/ns/persistence
    7.       http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
    8.     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 or when creating a JPA entity manager.

    1. <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:

    2.     org.eclipse.persistence.jpa.PersistenceProvider
    3. </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:

    JPA provider specific parameters are given under the properties element.

    1.    ...

    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:

    1. <property name="eclipselink.jdbc.platform"
    2.  value="org.eclipse.persistence.platform.database.H2Platform"/>
    3. <property name="eclipselink.jdbc.driver"
    4.           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:

    2.           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:

    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:

    1. <property name="eclipselink.logging.level"
    2.           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.

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

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

    1. <property name="eclipselink.ddl-generation.output-mode"
    2.           value="database"/>
    3.       </properties>
    5. </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