path: root/documentation/jpacontainer/jpacontainer-installation.asciidoc

---
title: Installing
order: 2
layout: page
---

[[jpacontainer.installation]]
= 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.

[[jpacontainer.installation.download]]
== Downloading the Package

Vaadin JPAContainer is available for download from the
link:http://vaadin.com/directory[Vaadin Directory]. Please see
<<dummy/../../../framework/addons/addons-downloading#addons.downloading,"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.


[[jpacontainer.installation.package]]
== Installation Package Content

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

[filename]#README#:: A readme file describing the package contents.

[filename]#LICENSE#:: The full license text for the library.

[filename]#vaadin-jpacontainer-3.x.x.jar#:: The actual Vaadin JPAContainer library.

[filename]#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.

[filename]#jpacontainer-tutorial.pdf#:: The tutorial in PDF format.

[filename]#jpacontainer-tutorial-html#:: The tutorial in HTML format.

[filename]#jpacontainer-addressbook-demo#:: The JPAContainer AddressBook Demo project covered in this tutorial. You can
compile and package the application as a WAR with " [command]#mvn#
[parameter]#package#" or launch it in the Jetty web browser with "
[command]#mvn# [parameter]#jetty:run#". You can also import the demo project in
Eclipse.




[[jpacontainer.installation.maven]]
== Downloading with Maven

The link:http://vaadin.com/directory[download page in Vaadin Directory] gives
the dependency declaration needed for retrieving the Vaadin JPAContainer library
with Maven.

[subs="normal"]
----
<dependency>
   <groupId>com.vaadin.addon</groupId>
   <artifactId>jpacontainer</artifactId>
   <version>[replaceable]##3.2.0##</version>
</dependency>
----

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

See <<dummy/../../../framework/addons/addons-maven#addons.maven,"Using Add-ons
in a Maven Project">> for detailed instructions for using a Vaadin add-on with
Maven.

[[jpacontainer.installation.maven.archetype]]
=== Using the Maven Archetype

If you wish to create a new JPAContainer-enabled Vaadin project with Maven, you
can use the [literal]#++vaadin-archetype-jpacontainer++# archetype. Please see
<<dummy/../../../framework/getting-started/getting-started-maven#getting-started.maven,"Using
Vaadin with Maven">> for details on creating a Vaadin project with a Maven
archetype.



[[jpacontainer.installation.libraries]]
== Including Libraries in Your Project

The Vaadin JPAContainer JAR must be included in the library folder of the web
application. It is located in [filename]#WEB-INF/lib# path in a web application.
In a normal Eclipse web projects the path is [filename]#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


[[jpacontainer.installation.configuration]]
== Persistence Configuration

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

* The persistence unit

* The persistence provider

* The database driver and connection

* Logging


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

[[jpacontainer.installation.configuration.schema]]
=== Persistence XML Schema

The beginning of a [filename]#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">
----


[[jpacontainer.installation.configuration.unit]]
=== Defining the Persistence Unit

The root element of the persistence definition is persistence-unit. The name of
the persistence unit is needed for creating [classname]#JPAContainer# instances
from a [classname]#JPAContainerFactory#, as described in
<<dummy/../../../framework/jpacontainer/jpacontainer-usage#jpacontainer.usage.jpacontainerfactory,"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 [literal]#++<class>++# element.
Alternatively, you can allow including unlisted classes for persistence by
overriding the [literal]#++exclude-unlisted-classes++# default as follows:


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

JPA provider specific parameters are given under the [literal]#++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.


[[jpacontainer.installation.configuration.database]]
=== 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 [literal]#++;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"/>
----


[[jpacontainer.installation.configuration.logging]]
=== 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
[literal]#++FINE++# logging level:


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


[[jpacontainer.installation.configuration.other]]
=== 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
[literal]#++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>
----



[[jpacontainer.installation.troubleshooting]]
== Troubleshooting

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

[classname]#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 [filename]#persistence.xml# file, or that the
[filename]#persistence.xml# is at a wrong place or has some other problem. Make
sure that the persistence unit name matches and the [filename]#persistence.xml#
is in [filename]#WEB-INF/classes/META-INF# folder in the deployment.

[classname]#java.lang.IllegalArgumentException#: The class is not an entity:: The class is missing from the set of persistent entities. If the
[filename]#persistence.xml# does not have [parameter]#exclude-unlisted-classes#
defined as [literal]#++false++#, the persistent entity classes should be listed
with [literal]#++<class>++# elements.