diff options
Diffstat (limited to 'documentation/jpacontainer/jpacontainer-installation.asciidoc')
| -rw-r--r-- | documentation/jpacontainer/jpacontainer-installation.asciidoc | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/documentation/jpacontainer/jpacontainer-installation.asciidoc b/documentation/jpacontainer/jpacontainer-installation.asciidoc new file mode 100644 index 0000000000..b678746712 --- /dev/null +++ b/documentation/jpacontainer/jpacontainer-installation.asciidoc @@ -0,0 +1,311 @@ +--- +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. + + +---- +<dependency> + <groupId>com.vaadin.addon</groupId> + <artifactId>jpacontainer-addon</artifactId> + <version>3.1.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. + + + + + + |