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