openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mik...@apache.org
Subject svn commit: r1409057 [6/25] - in /openjpa/site: branches/ trunk/ trunk/cgi-bin/ trunk/content/ trunk/content/images/ trunk/lib/ trunk/resources/ trunk/templates/
Date Wed, 14 Nov 2012 01:50:14 GMT
Added: openjpa/site/trunk/content/building
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/building?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/building (added)
+++ openjpa/site/trunk/content/building Wed Nov 14 01:49:37 2012
@@ -0,0 +1,401 @@
+{excerpt:hidden=true}How to build OpenJPA from source{excerpt}
+
+h1. Contents
+{toc}
+
+h1. Building OpenJPA
+
+See [Build and Runtime Dependencies] for details on the required Java levels.
+
+h2. Maven
+
+h3. Command Line Builds
+
+These instructions describe how to check out the current OpenJPA source code (from the Subversion source code management repository) and build it (using the Apache Maven 2 build tool). They are written for use from the console, and are known to work on Linux, Mac OSX and Windows.
+
+ # Ensure that you have Java installed and in your path by running: {{java -fullversion}}
+ # Install the build tool, Apache Maven 2.2.1 or later, from http://maven.apache.org/. If it is installed correctly, typing {{mvn -v}} from the console will result in text like {{Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)}}
+ # Install Subversion v1.4.x or newer from http://subversion.apache.org/. If it is installed correctly, typing the following command should output help information: {{svn help}} or {{svn --version}}
+ # Create a new directory you want to do your work in, then change to that directory from the console.
+ # Check out the sources by running: {{svn co https://svn.apache.org/repos/asf/openjpa/trunk openjpa-trunk}}. It will check out the sources to the openjpa-trunk directory. More information on checking out the OpenJPA sources can be found on the [Source Code] page.
+ # Change to the openjpa-trunk directory, which has already been created in the previous step.
+ # Build OpenJPA by running: {{mvn package}} or better {{mvn install}}. The first time you run the build, many dependencies are automatically resolved and downloaded. *It is common for dependency downloading to fail the first time, which will fail the build.* If any of these dependency downloads fail, just re-run the command. You may also add the following to your {{~/.m2/setting.xml}} file (see http://maven.apache.org/guides/mini/guide-mirror-settings.html)
+
+{code:xml}
+<settings>
+    <mirrors>
+        <mirror>
+            <id>repo.mergere.com</id>
+            <url>http://repo.mergere.com/maven2</url>
+            <mirrorOf>central</mirrorOf>
+        </mirror>
+    </mirrors>
+</settings>
+{code}
+
+ If any tests fail, and you want to ignore the failures, instead run:
+
+  {{mvn package -DfailIfNoTests=false}}
+
+ or
+
+  {{mvn package -DskipTests}}
+
+
+An example session is as follows:
+
+{noformat}
+$ cd /tmp/
+
+$ java -version
+
+java version "1.6.0"
+Java(TM) SE Runtime Environment (build 1.6.0-b105)
+Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode, sharing)
+
+$ mvn -v
+
+Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)
+Java version: 1.6.0
+Java home: /alt/sun160/jre
+Default locale: en_US, platform encoding: UTF-8
+OS name: "linux" version: "2.6.18-1.2798.fc6" arch: "i386" Family: "unix"
+
+$ svn --version
+
+svn, version 1.4.3 (r23084)
+   compiled Jan 18 2007, 07:47:40
+
+$ svn co https://svn.apache.org/repos/asf/openjpa/trunk/
+
+A  trunk/openjpa-lib
+A  trunk/openjpa-lib/src
+A  trunk/openjpa-lib/src/test
+A  trunk/openjpa-lib/src/test/java
+A  trunk/openjpa-lib/src/test/java/org
+A  trunk/openjpa-lib/src/test/java/org/apache
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa/lib
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa/lib/test
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa/lib/test/AbstractTestCase.java
+
+ ...
+
+A  trunk/openjpa-persistence/pom.xml
+Checked out revision 1065345.
+
+$ cd trunk/
+
+$ mvn compile
+
+[INFO] Scanning for projects...
+[INFO] Reactor build order: 
+[INFO]   OpenJPA Parent POM
+[INFO]   OpenJPA Utilities Library
+[INFO]   OpenJPA Kernel
+[INFO]   OpenJPA JDBC
+[INFO]   OpenJPA Persistence
+[INFO]   OpenJPA Persistence JDBC
+[INFO]   OpenJPA Persistence Locking Tests
+[INFO]   OpenJPA XML Store
+[INFO]   OpenJPA Slice
+[INFO]   OpenJPA JEST
+[INFO]   OpenJPA Aggregate Jar
+[INFO]   OpenJPA Aggregate Jar with Dependencies
+[INFO]   OpenJPA Project Docs and Assemblies
+[INFO]   OpenJPA Examples
+[INFO]   OpenJPA Examples - Simple
+[INFO]   OpenJPA Examples - image-gallery
+[INFO]   OpenJPA Examples - OpenBooks
+[INFO]   OpenJPA Integration Tests
+[INFO]   OpenJPA Integration Tests - Daytrader
+[INFO]   OpenJPA Integration Tests - Examples
+[INFO]   OpenJPA Integration Tests - SLF4JLogFactory
+[INFO]   OpenJPA Integration Tests - JPA TCK
+[INFO]   OpenJPA Integration Tests - Bean Validation
+[INFO]   OpenJPA Integration Tests - JMX Platform MBeans
+[INFO] ------------------------------------------------------------------------
+[INFO] Building OpenJPA Parent POM
+[INFO]    task-segment: [compile]
+[INFO] ------------------------------------------------------------------------
+
+ ...
+
+[INFO] 
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO] ------------------------------------------------------------------------
+[INFO] OpenJPA Parent POM .................................... SUCCESS [1:23.143s]
+[INFO] OpenJPA Utilities Library ............................. SUCCESS [13.749s]
+[INFO] OpenJPA Kernel ........................................ SUCCESS [19.251s]
+[INFO] OpenJPA JDBC .......................................... SUCCESS [14.351s]
+[INFO] OpenJPA Persistence ................................... SUCCESS [10.254s]
+[INFO] OpenJPA Persistence JDBC .............................. SUCCESS [46.774s]
+[INFO] OpenJPA Persistence Locking Tests ..................... SUCCESS [15.183s]
+[INFO] OpenJPA XML Store ..................................... SUCCESS [11.788s]
+[INFO] OpenJPA Slice ......................................... SUCCESS [4.437s]
+[INFO] OpenJPA JEST .......................................... SUCCESS [4.854s]
+[INFO] OpenJPA Aggregate Jar ................................. SUCCESS [10.729s]
+[INFO] OpenJPA Aggregate Jar with Dependencies ............... SUCCESS [6.761s]
+[INFO] OpenJPA Project Docs and Assemblies ................... SUCCESS [1:41.937s]
+[INFO] OpenJPA Examples ...................................... SUCCESS [0.663s]
+[INFO] OpenJPA Examples - Simple ............................. SUCCESS [1.475s]
+[INFO] OpenJPA Examples - image-gallery ...................... SUCCESS [3.920s]
+[INFO] OpenJPA Examples - OpenBooks .......................... SUCCESS [12.961s]
+[INFO] OpenJPA Integration Tests ............................. SUCCESS [0.381s]
+[INFO] OpenJPA Integration Tests - Daytrader ................. SUCCESS [7.565s]
+[INFO] OpenJPA Integration Tests - Examples .................. SUCCESS [0.269s]
+[INFO] OpenJPA Integration Tests - SLF4JLogFactory ........... SUCCESS [1.977s]
+[INFO] OpenJPA Integration Tests - JPA TCK ................... SUCCESS [0.248s]
+[INFO] OpenJPA Integration Tests - Bean Validation ........... SUCCESS [3.213s]
+[INFO] OpenJPA Integration Tests - JMX Platform MBeans ....... SUCCESS [7.729s]
+[INFO] ------------------------------------------------------------------------
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 6 minutes 26 seconds
+[INFO] Finished at: Sun Jan 30 19:43:50 CET 2011
+[INFO] Final Memory: 92M/158M
+[INFO] ------------------------------------------------------------------------
+
+
+$ mvn package -DskipTests
+
+[INFO] Scanning for projects...
+
+...
+
+[INFO] Building zip: /tmp/trunk/openjpa-project/target/site/downloads/apache-openjpa-2.2.0-SNAPSHOT-binary.zip
+
+... 
+
+$ ls -lh openjpa-project/target/site/downloads/
+
+total 40M
+-rw-r--r-- 1 milosz milosz 15M Jan 30 19:41 apache-openjpa-2.2.0-SNAPSHOT-binary.zip
+-rw-r--r-- 1 milosz milosz 25M Jan 30 19:43 apache-openjpa-2.2.0-SNAPSHOT-source.zip
+
+{noformat}
+
+
+h3. Executing various Maven build tasks
+
+h5. Running just the "TestPersistence" test case
+
+{noformat}
+mvn test -Dtest=TestPersistence
+{noformat}
+
+h5. Running tests with Java 2 security enabled
+
+{noformat}
+mvn test -Penable-security
+{noformat}
+
+h5. Building and running only the examples included in the distribution
+
+{noformat}
+mvn -DskipTests -Pexamples-profile integration-test
+{noformat}
+
+h5. Building just the javadoc
+
+First install the jars:
+
+{noformat}
+mvn install -DskipTests
+{noformat}
+
+Then build the javadoc:
+
+{noformat}
+mvn package -DskipTests -Pjavadoc-profile
+{noformat}
+
+The javadoc will be output to {{target/site/apidocs/index.html}}.
+
+h5. Building just the docbook documentation
+
+{noformat}
+set MAVEN_OPTS=-Xmx512m
+mvn -f openjpa-project/pom.xml process-resources -Pdocbook-profile
+{noformat}
+
+The manual HTML will be output to {{openjpa-project/target/manual/manual.html}}.
+
+h5. Building with JDK 1.4 module verification (only for versions of OpenJPA prior to svn revision 640685)
+
+{noformat}
+mvn compile -Djava14.jar=C:\Program Files\Java\j2re1.4.2_07\lib\rt.jar compile
+{noformat}
+
+Specifying the "java14.jar" system property will cause the JDK-1.4-dependent modules to be compiled with the value as the bootclasspath to the compiler. This can be useful to ensure that modifications and additions do not violate the JDK version restriction of the module. Since the runtime jar location is platform, version, and installation dependent, the exact location of the runtime jar will vary, which is why it needs to be manually specified.
+
+h2. Eclipse with Command-line Maven utilities
+
+# Checkout the source as described above
+# Build the source using Maven as described above
+# Create the Eclipse Metadata - \\
+{noformat}
+mvn eclipse:eclipse
+{noformat}
+** If this is the first project in your workspace to use maven artifacts you need to create a classpath variable named M2_REPO which contains the full path to your local repository. The eclipse plugin can do this for you with the following command \\
+{noformat}
+mvn eclipse:configure-workspace -Declipse.workspace=${path to your workspace} 
+{noformat}
+# Start Eclipse (3.2 - 3.4 SR2 are known to work) and create a new workspace
+# Import the OpenJPA projects, by:
+** Select File --> Import... --> General - Existing Projects into Workspace --> Next
+** Select root directory = <svn checkout location above>
+** Deselect the openjpa-examples project
+** Press Finish
+# A few fixups will be required to remove the errors that exist in the imported projects...
+** openjpa-kernel -> Properties -> Java Build Path -> Source -> Add Folders
+*** add target/generated-sources/javacc
+** openjpa-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-examples.  Open up src/main/java and select ReverseMapping folder.  Right mouse click.
+*** Select Build Path -> Exclude
+# For each imported project, you'll need to edit the build properties to remove an incorrect dependency:
+** Project --> Properties --> Java Build Path --> Source
+** Remove openjpa-project from the list of source folders
+
+For Java SE 5 users building from the 2.0.x branch, you will need to exclude some Java SE 6 specific classes by performing the following steps for the source:
+# Open the Properties for openjpa-persistence
+# Select Java Build Path --> Source
+# Edit the openjpa-persistence/src/main/java --> Excluded setting to include the following:
+{noformat}
+org/apache/openjpa/persistence/meta/AnnotationProcessor6.java
+org/apache/openjpa/persistence/meta/CompileTimeLogger.java
+org/apache/openjpa/persistence/meta/SourceAnnotationHandler.java
+{noformat}
+
+h2. Eclipse with M2Eclipse plugin
+
+# Checkout the source as described above
+# Build the source using Maven as described above
+# Start Eclipse (3.5 Galileo is recommended) and create a new workspace
+# Good references for this M2Eclipse plugin (need to install the plugin into your Eclipse environment)
+** http://m2eclipse.codehaus.org/
+** http://docs.codehaus.org/display/M2ECLIPSE/Home
+** http://www.theserverside.com/tt/articles/article.tss?l=Introductiontom2eclipse
+# Import the OpenJPA projects, by:
+** Select File --> Import... --> General -> Maven Projects --> Next
+** Select root directory = <svn checkout location above>
+** All of the pom.xml files should be pre-selected for the svn checkout location
+** You can affect the naming convention used for the generated Eclipse projects (one for each Maven module).  Click on Advanced and fill in the Name Template field.  I prefer "TRUNK-\[artifactId\]" since it helps with workspace organization, but it's your choice.
+** Press Finish
+** *Note:*  You may get a popup internal error at the end of this Import processing.  Not sure what the problem is, but it doesn't seem to affect the usage.
+# A few fixups will be required to remove the errors that exist in the imported projects...
+** openjpa-kernel -> Properties -> Java Build Path -> Source -> Add Folders
+*** add target/generated-sources/javacc
+** openjpa-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-examples.  Open up src/main/java and select ReverseMapping folder.  Right mouse click.
+*** Select Build Path -> Exclude
+
+For Java SE 5 users building from the 2.0.x branch, you will need to exclude some Java SE 6 specific classes by performing the following steps for the source:
+# Open the Properties for BR20-openjpa-persistence (or whatever your naming convention is)
+# Select Java Build Path --> Source
+# Edit the openjpa-persistence/src/main/java --> Excluded setting to include the following:
+{noformat}
+org/apache/openjpa/persistence/meta/AnnotationProcessor6.java
+org/apache/openjpa/persistence/meta/CompileTimeLogger.java
+org/apache/openjpa/persistence/meta/SourceAnnotationHandler.java
+{noformat}
+
+\\
+
+h2. Common 2.x Build Problems
+
+h3. Wrong Maven Level
+
+Example Maven output -
+{code:none}
+[INFO] [enforcer:enforce {execution: default}]
+[WARNING] Rule 0: org.apache.maven.plugins.enforcer.RequireMavenVersion failed with message:
+Detected Maven Version: 2.0.10 is not in the allowed range [2.2.1,).
+[INFO] ------------------------------------------------------------------------
+[ERROR] BUILD ERROR
+[INFO] ------------------------------------------------------------------------
+[INFO] Some Enforcer rules have failed. Look above for specific messages explaining why the rule failed.
+{code}
+Solution - Upgrade to Maven 2.2.1 or later
+
+h3. Wrong Java Level
+
+Example Maven output -
+{code:none}
+[INFO] [enforcer:enforce {execution: default}]
+[WARNING] Rule 1: org.apache.maven.plugins.enforcer.RequireJavaVersion failed with message:
+Detected JDK Version: 1.5.0-19 is not in the allowed range [1.6,).
+[INFO] ------------------------------------------------------------------------
+[ERROR] BUILD ERROR
+[INFO] ------------------------------------------------------------------------
+[INFO] Some Enforcer rules have failed. Look above for specific messages explaining why the rule failed.
+{code}
+Solution - Upgrade to latest Sun JDK 1.6.0 or IBM 6 SDK
+Note - OpenJDK and Java SE 7 are not supported at this time.
+
+h3. Missing License Headers
+
+Example Maven output -
+{code:none}
+. . .
+[INFO] ------------------------------------------------------------------------
+[INFO] Building OpenJPA Parent POM
+[INFO]    task-segment: [clean, install]
+[INFO] ------------------------------------------------------------------------
+. . .
+[INFO] [enforcer:enforce {execution: default}]
+[INFO] [source:test-jar {execution: attach-sources}]
+[INFO] [ianal:verify-legal-files {execution: default}]
+[INFO] [apache-rat:check {execution: default}]
+[INFO] Exclude: **/javax.persistence.spi.PersistenceProvider
+[INFO] Exclude: **/javax.annotation.processing.Processor
+[INFO] Exclude: **/*.rsrc
+[INFO] Exclude: **/org.apache.openjpa.revision.properties
+[INFO] Exclude: scripts/*.list
+[INFO] Exclude: scripts/*.options
+[INFO] Exclude: scripts/*.dict
+[INFO] Exclude: **/.*/**
+[INFO] Exclude: **/target/**/*
+[INFO] Exclude: **/dependency-reduced-pom.xml
+[INFO] Exclude: **/*.log
+[INFO] Exclude: **/maven-eclipse.xml
+[INFO] Exclude: **/rat.txt
+[INFO] Exclude: **/internal-repository/**
+[INFO] ------------------------------------------------------------------------
+[ERROR] BUILD FAILURE
+[INFO] ------------------------------------------------------------------------
+[INFO] Too many unapproved licenses: 1
+[INFO] ------------------------------------------------------------------------
+{code}
+For the module that failed to build (which in the case above is the root pom.xml) open the target/rat.txt file and search for any "????" occurrences, like -
+{code:none}
+. . .
+*****************************************************
+  Files with Apache License headers will be marked AL
+  Binary files (which do not require AL headers) will be marked B
+  Compressed archives will be marked A
+  Notices, licenses etc will be marked N
+  N     LICENSE.txt
+  N     NOTICE.txt
+  AL    openjpa/pom.xml
+  AL    openjpa/src/main/appended-resources/META-INF/LICENSE.vm
+  AL    openjpa/src/main/appended-resources/META-INF/NOTICE.vm
+ !????? OPENJPA-1621.patch
+. . .
+{code}
+Solution - either add the missing ASL 2.0 license header, remove the file from your local working directory (if it is a temporary file that should not be added to svn), or ask on the dev@openjpa list if the file can be added to the exclude list for the apache-rat checks.
+
+
+\\

Added: openjpa/site/trunk/content/building-and-running-openbooks
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/building-and-running-openbooks?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/building-and-running-openbooks (added)
+++ openjpa/site/trunk/content/building-and-running-openbooks Wed Nov 14 01:49:37 2012
@@ -0,0 +1,131 @@
+h2. Instructions to download and run OpenBooks Demo
+
+OpenBooks comes with
+
+* complete source code
+* build scripts to demonstrate how to build a typical OpenJPA application and package it for JSE or JEE environment
+* scripts to run OpenBooks in on your local database installation.
+
+
+Follow the simple instructions below to build and run OpenBooks:
+
+h2. Download Instructions
+
+OpenBooks can be checked out from OpenJPA repository.
+
+ {{$ svn co}} {{[https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks]}}.
+
+will check out the source code and build scripts of OpenBooks in current directory.
+
+OpenBooks requires following software environment to run:
+
+* Java Runtime version 6.0 or higher
+* OpenJPA Libraries version 2.0 or higher
+* Ant version 1.6 or higher
+* Any JDBC complaint database supported by OpenJPA (embedded Derby is the default).
+
+
+
+h2. Configure build and run environment
+
+OpenBooks builds with Ant. The Ant build script is somewhat involved because OpenBooks can be built and packaged either as a JSE (Swing based) application or a JEE Web Application. By default, OpenBooks is built as a JSE application.
+
+OpenBooks can be built in JSE and JEE mode -- and to keep things simple the common build steps are available in main build script {{build.xml}} while JSE and JEE specific packaging steps are described in separate {{build.jse.xml}} and {{build.jee.xml}}, respectively. Furthermore, for JEE, the deployment step is further refined for each application server. See {{build.jee.was.xml}} and {{build.jee.liberty.xml}} for build and installation steps for WebSphere Application Server and the Liberty Profile for WAS, respectively.
+
+Before you run a build, configure the build environment by editing {{openjpa-examples/openbooks/build.properties}}. Essentially, you need to
+
+* Point {{openjpa.lib}} variable to the local directory where OpenJPA class library(ies) reside. Notice that the variable points to a directory and not a {{\*.jar}} file. All {{\*.jar}} files found under the directory are included in compilation classpath. OpenJPA version 2.0, however, is also available with all its runtime dependencies (such as JPA specification API, Apache Commons Collections and others) packaged together in a _single_ library (lib).
+
+*Note:&nbsp;* Access to the OpenJPA class libraries is easier if you have a Maven repository (.m2) available on your system.&nbsp; In this case, all that is required is to update the {{openjpa.version}} variable to point at the proper OpenJPA SNAPSHOT version.
+
+* Ideally, a JPA-compliant application _should_ not require provider-specific library during compilation. OpenBooks persistent domain model and application logic also does not use any OpenJPA specific features, but OpenJPA libraries are still used during compilation because bytecode for persistent entities are _enhanced_ as a post-compilation step. This bytecode enhancement is not essential but an important step for using OpenJPA.
+
+The next step is to configure runtime configuration descriptors and environment variables.
+* JSE
+** Edit {{persistence.xml}} located in {{openjpa-examples/openbooks/src/main/resources/META-INF}} directory. Modify the {{javax.persistence.jdbc.driver}} and {{javax.persistence.jdbc.url}} property to suit your local database and its driver.
+** Edit {{openjpa-examples/openbooks/run.properties}} to specify location of OpenJPA class libraries and JDBC Driver used in runtime classpath.  Here again, the use of the {{openjpa.version}} variable with a Maven repository makes the library and jdbc driver configuration easy.
+
+* JEE
+** You may already have a JTA data source configured and registered in JNDI. Of course, then the appropriate configuration is to be edited accordingly in the {{<jta-data-source>}} and {{<non-jta-data-source>}} clauses. See {{persistence.jee.was.xml}} for WebSphere environment, or {{persistence.jee.liberty.xml}} for the Liberty Profile. 
+** OpenJPA library and JDBC drivers are configured in JEE server and hence variables in this file are irrelevant.
+** More information on the build and installation of the OpenBooks example for application servers can be found in the [WebSphere Application Server|#websphere] and [Liberty Profile|#liberty] deployment sections.
+
+
+
+Both {{build.properties}} and {{run.properties}} files are commented in-place on what is to be edited.
+
+
+h2. Build OpenBooks from source
+
+Once you have configured the environment, simply issue (from the {{openjpa-examples/openbooks}} directory):
+
+ {{$ ant}}
+
+or
+
+ {{$ ant \-Dbuild.mode=jee}}
+
+The default target of the ant script will
+* generate metamodel classes (required for Criteria API)
+* compile the source code
+* enhance the persistence domain model
+* package the application based on the build.mode as a Swing-based application or a Web Application Archive.
+* copy the deployable artifacts to {{target}} and {{target/openbooks}} directories relative to the current directory.
+
+
+h2. Deploy OpenBooks in an Application Server
+
+Deployment techniques and configuration vary across JEE compliant application servers. Hence, OpenBooks does not provide an uber-deployment script for all application server. Instead, application server specific steps are encoded in separate build scripts for each application server. Using generic build as described in the previous section, the {{target/openbooks.war}} web archive needs to be deployed manually.
+
+{anchor:websphere}
+h3. WebSphere Application Server
+
+For WebSphere Application Server, automated build scripts are available in {{build.jee.was.xml}}. WebSphere deployment needs to be triggered by {{ws_ant}} utility as follows
+
+ {{$ ws_ant \-Dbuild.mode=jee \-Dappserver=was \-Dwas.home=<WAS_HOME>}}
+
+where {{<WAS_HOME>}} denotes the root directory where WAS V7 with JPA 2.0 feature pack has been installed (at a minimum). Yes, OpenBooks requires features defined by the JPA 2.0 specification, thus the use of the WAS V7 JPA 2.0 feature pack is a minimum requirement. Further information on this feature pack is available [here|http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27018836] or [WebSphere in general|http://www-01.ibm.com/software/websphere/].
+
+The WebSphere specific build will configure appropriate JTA data sources using a python script (found under {{openbooks/scripts/}} directory before deploying OpenBooks as a web application. The script assumes a single server instance. If multiple profiles exist, the script will use the first server profile.
+
+{anchor:liberty}
+h3. Liberty Profile in WebSphere Application Server v8.5
+
+For the Liberty Profile in WebSphere Application Server v8.5, automated build scripts are available in {{build.jee.liberty.xml}}. Liberty Profile deployment is very easy and needs to be triggered by {{ant}} as follows
+
+ {{$ ant \-Dbuild.mode=jee \-Dappserver=liberty \-Dliberty.home=<WAS_HOME>/wlp \-Dliberty.server=<server name>}}
+
+where {{<WAS_HOME>}} denotes the root directory where WAS v8.5 has been installed, and <server name> is the name of your Liberty Profile server.  Instead of specifying these two variables, {{liberty.home}} and {{liberty.server}}, you could modify the build variables in the {{build.jee.liberty.xml}} file.  
+
+By specifying {{liberty.home}} and {{liberty.server}}, the ant script will attempt to "deploy" the resulting openbooks.war application to the designated Liberty server.  Additional configuration of your Liberty server may be required before OpenBooks will work.  For example, you will need to specify the {{jpa-2.0}} and {{jdbc-4.0}} features in your server.xml.  You will also need to define the JTA datasources used by the OpenBooks application via your server.xml file.  Examples of a derby configuration can be found in the {{openbooks/scripts/liberty}} directory.
+
+Additional information on the Liberty Profile can be found [here|http://www.wasdev.net/].  General WebSphere information can be found [here|http://www-01.ibm.com/software/websphere/].
+
+h2. Run OpenBooks
+
+If you have built OpenBooks for JSE, then go to the {{openjpa-examples/openbooks/target/openbooks}} directory.
+
+Invoke the Ant script to run OpenBooks
+{{$ ant \-f run.xml}}
+
+
+If you have built OpenBooks for JEE, a Web Application Archive {{openbooks.war}} will be created in {{openjpa-examples/openbooks/target}} directory. You need to deploy {{openbooks.war}} to a JEE Application Server. Once deployed, you can point a browser to Application Server URL
+
+ {{http:// < app server host >:<port>/openbooks/}}
+
+For example,
+
+ {{http://localhost:9080/openbooks/}}
+
+to access OpenBooks as a web application.
+
+
+h2. Populate OpenBooks Database
+
+OpenBooks checks for existing data at first connection to the database. If the database is empty, the schema is defined and populated with initial data. However, you can explicitly populate the database in JSE build.
+
+*Note:* By default, the OpenBooks example uses and populates an Embedded Derby instance on "first touch".  So, no further configuration or loading is required for the default configuration.
+
+Edit {{load.properties}} to specify load parameters such as number of Books etc. OpenBooks uses this data to populate a database with some sample data. This example file has some typical values. If you are satisfied with it, you can leave them as it is. Then invoke the Ant script
+
+ {{$ ant \-f run.xml load}}
\ No newline at end of file

Added: openjpa/site/trunk/content/building-and-running-openbooks.cwiki
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/building-and-running-openbooks.cwiki?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/building-and-running-openbooks.cwiki (added)
+++ openjpa/site/trunk/content/building-and-running-openbooks.cwiki Wed Nov 14 01:49:37 2012
@@ -0,0 +1,131 @@
+h2. Instructions to download and run OpenBooks Demo
+
+OpenBooks comes with
+
+* complete source code
+* build scripts to demonstrate how to build a typical OpenJPA application and package it for JSE or JEE environment
+* scripts to run OpenBooks in on your local database installation.
+
+
+Follow the simple instructions below to build and run OpenBooks:
+
+h2. Download Instructions
+
+OpenBooks can be checked out from OpenJPA repository.
+
+ {{$ svn co}} {{[https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks]}}.
+
+will check out the source code and build scripts of OpenBooks in current directory.
+
+OpenBooks requires following software environment to run:
+
+* Java Runtime version 6.0 or higher
+* OpenJPA Libraries version 2.0 or higher
+* Ant version 1.6 or higher
+* Any JDBC complaint database supported by OpenJPA (embedded Derby is the default).
+
+
+
+h2. Configure build and run environment
+
+OpenBooks builds with Ant. The Ant build script is somewhat involved because OpenBooks can be built and packaged either as a JSE (Swing based) application or a JEE Web Application. By default, OpenBooks is built as a JSE application.
+
+OpenBooks can be built in JSE and JEE mode -- and to keep things simple the common build steps are available in main build script {{build.xml}} while JSE and JEE specific packaging steps are described in separate {{build.jse.xml}} and {{build.jee.xml}}, respectively. Furthermore, for JEE, the deployment step is further refined for each application server. See {{build.jee.was.xml}} and {{build.jee.liberty.xml}} for build and installation steps for WebSphere Application Server and the Liberty Profile for WAS, respectively.
+
+Before you run a build, configure the build environment by editing {{openjpa-examples/openbooks/build.properties}}. Essentially, you need to
+
+* Point {{openjpa.lib}} variable to the local directory where OpenJPA class library(ies) reside. Notice that the variable points to a directory and not a {{\*.jar}} file. All {{\*.jar}} files found under the directory are included in compilation classpath. OpenJPA version 2.0, however, is also available with all its runtime dependencies (such as JPA specification API, Apache Commons Collections and others) packaged together in a _single_ library (lib).
+
+*Note:&nbsp;* Access to the OpenJPA class libraries is easier if you have a Maven repository (.m2) available on your system.&nbsp; In this case, all that is required is to update the {{openjpa.version}} variable to point at the proper OpenJPA SNAPSHOT version.
+
+* Ideally, a JPA-compliant application _should_ not require provider-specific library during compilation. OpenBooks persistent domain model and application logic also does not use any OpenJPA specific features, but OpenJPA libraries are still used during compilation because bytecode for persistent entities are _enhanced_ as a post-compilation step. This bytecode enhancement is not essential but an important step for using OpenJPA.
+
+The next step is to configure runtime configuration descriptors and environment variables.
+* JSE
+** Edit {{persistence.xml}} located in {{openjpa-examples/openbooks/src/main/resources/META-INF}} directory. Modify the {{javax.persistence.jdbc.driver}} and {{javax.persistence.jdbc.url}} property to suit your local database and its driver.
+** Edit {{openjpa-examples/openbooks/run.properties}} to specify location of OpenJPA class libraries and JDBC Driver used in runtime classpath.  Here again, the use of the {{openjpa.version}} variable with a Maven repository makes the library and jdbc driver configuration easy.
+
+* JEE
+** You may already have a JTA data source configured and registered in JNDI. Of course, then the appropriate configuration is to be edited accordingly in the {{<jta-data-source>}} and {{<non-jta-data-source>}} clauses. See {{persistence.jee.was.xml}} for WebSphere environment, or {{persistence.jee.liberty.xml}} for the Liberty Profile. 
+** OpenJPA library and JDBC drivers are configured in JEE server and hence variables in this file are irrelevant.
+** More information on the build and installation of the OpenBooks example for application servers can be found in the [WebSphere Application Server|#websphere] and [Liberty Profile|#liberty] deployment sections.
+
+
+
+Both {{build.properties}} and {{run.properties}} files are commented in-place on what is to be edited.
+
+
+h2. Build OpenBooks from source
+
+Once you have configured the environment, simply issue (from the {{openjpa-examples/openbooks}} directory):
+
+ {{$ ant}}
+
+or
+
+ {{$ ant \-Dbuild.mode=jee}}
+
+The default target of the ant script will
+* generate metamodel classes (required for Criteria API)
+* compile the source code
+* enhance the persistence domain model
+* package the application based on the build.mode as a Swing-based application or a Web Application Archive.
+* copy the deployable artifacts to {{target}} and {{target/openbooks}} directories relative to the current directory.
+
+
+h2. Deploy OpenBooks in an Application Server
+
+Deployment techniques and configuration vary across JEE compliant application servers. Hence, OpenBooks does not provide an uber-deployment script for all application server. Instead, application server specific steps are encoded in separate build scripts for each application server. Using generic build as described in the previous section, the {{target/openbooks.war}} web archive needs to be deployed manually.
+
+{anchor:websphere}
+h3. WebSphere Application Server
+
+For WebSphere Application Server, automated build scripts are available in {{build.jee.was.xml}}. WebSphere deployment needs to be triggered by {{ws_ant}} utility as follows
+
+ {{$ ws_ant \-Dbuild.mode=jee \-Dappserver=was \-Dwas.home=<WAS_HOME>}}
+
+where {{<WAS_HOME>}} denotes the root directory where WAS V7 with JPA 2.0 feature pack has been installed (at a minimum). Yes, OpenBooks requires features defined by the JPA 2.0 specification, thus the use of the WAS V7 JPA 2.0 feature pack is a minimum requirement. Further information on this feature pack is available [here|http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27018836] or [WebSphere in general|http://www-01.ibm.com/software/websphere/].
+
+The WebSphere specific build will configure appropriate JTA data sources using a python script (found under {{openbooks/scripts/}} directory before deploying OpenBooks as a web application. The script assumes a single server instance. If multiple profiles exist, the script will use the first server profile.
+
+{anchor:liberty}
+h3. Liberty Profile in WebSphere Application Server v8.5
+
+For the Liberty Profile in WebSphere Application Server v8.5, automated build scripts are available in {{build.jee.liberty.xml}}. Liberty Profile deployment is very easy and needs to be triggered by {{ant}} as follows
+
+ {{$ ant \-Dbuild.mode=jee \-Dappserver=liberty \-Dliberty.home=<WAS_HOME>/wlp \-Dliberty.server=<server name>}}
+
+where {{<WAS_HOME>}} denotes the root directory where WAS v8.5 has been installed, and <server name> is the name of your Liberty Profile server.  Instead of specifying these two variables, {{liberty.home}} and {{liberty.server}}, you could modify the build variables in the {{build.jee.liberty.xml}} file.  
+
+By specifying {{liberty.home}} and {{liberty.server}}, the ant script will attempt to "deploy" the resulting openbooks.war application to the designated Liberty server.  Additional configuration of your Liberty server may be required before OpenBooks will work.  For example, you will need to specify the {{jpa-2.0}} and {{jdbc-4.0}} features in your server.xml.  You will also need to define the JTA datasources used by the OpenBooks application via your server.xml file.  Examples of a derby configuration can be found in the {{openbooks/scripts/liberty}} directory.
+
+Additional information on the Liberty Profile can be found [here|http://www.wasdev.net/].  General WebSphere information can be found [here|http://www-01.ibm.com/software/websphere/].
+
+h2. Run OpenBooks
+
+If you have built OpenBooks for JSE, then go to the {{openjpa-examples/openbooks/target/openbooks}} directory.
+
+Invoke the Ant script to run OpenBooks
+{{$ ant \-f run.xml}}
+
+
+If you have built OpenBooks for JEE, a Web Application Archive {{openbooks.war}} will be created in {{openjpa-examples/openbooks/target}} directory. You need to deploy {{openbooks.war}} to a JEE Application Server. Once deployed, you can point a browser to Application Server URL
+
+ {{http:// < app server host >:<port>/openbooks/}}
+
+For example,
+
+ {{http://localhost:9080/openbooks/}}
+
+to access OpenBooks as a web application.
+
+
+h2. Populate OpenBooks Database
+
+OpenBooks checks for existing data at first connection to the database. If the database is empty, the schema is defined and populated with initial data. However, you can explicitly populate the database in JSE build.
+
+*Note:* By default, the OpenBooks example uses and populates an Embedded Derby instance on "first touch".  So, no further configuration or loading is required for the default configuration.
+
+Edit {{load.properties}} to specify load parameters such as number of Books etc. OpenBooks uses this data to populate a database with some sample data. This example file has some typical values. If you are satisfied with it, you can leave them as it is. Then invoke the Ant script
+
+ {{$ ant \-f run.xml load}}
\ No newline at end of file

Propchange: openjpa/site/trunk/content/building-and-running-openbooks.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: openjpa/site/trunk/content/building-and-running-openbooks.mdtext
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/building-and-running-openbooks.mdtext?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/building-and-running-openbooks.mdtext (added)
+++ openjpa/site/trunk/content/building-and-running-openbooks.mdtext Wed Nov 14 01:49:37 2012
@@ -0,0 +1,235 @@
+Title: Building and Running OpenBooks
+<a name="BuildingandRunningOpenBooks-InstructionstodownloadandrunOpenBooksDemo"></a>
+## Instructions to download and run OpenBooks Demo
+
+OpenBooks comes with
+
+* complete source code
+* build scripts to demonstrate how to build a typical OpenJPA application
+and package it for JSE or JEE environment
+* scripts to run OpenBooks in on your local database installation.
+
+
+Follow the simple instructions below to build and run OpenBooks:
+
+<a name="BuildingandRunningOpenBooks-DownloadInstructions"></a>
+## Download Instructions
+
+OpenBooks can be checked out from OpenJPA repository.
+
+ *$ svn co* {{[https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks](https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks)
+}}.
+
+will check out the source code and build scripts of OpenBooks in current
+directory.
+
+OpenBooks requires following software environment to run:
+
+* Java Runtime version 6.0 or higher
+* OpenJPA Libraries version 2.0 or higher
+* Ant version 1.6 or higher
+* Any JDBC complaint database supported by OpenJPA (embedded Derby is the
+default).
+
+
+
+<a name="BuildingandRunningOpenBooks-Configurebuildandrunenvironment"></a>
+## Configure build and run environment
+
+OpenBooks builds with Ant. The Ant build script is somewhat involved
+because OpenBooks can be built and packaged either as a JSE (Swing based)
+application or a JEE Web Application. By default, OpenBooks is built as a
+JSE application.
+
+OpenBooks can be built in JSE and JEE mode -- and to keep things simple the
+common build steps are available in main build script *build.xml* while
+JSE and JEE specific packaging steps are described in separate
+*build.jse.xml* and *build.jee.xml*, respectively. Furthermore, for
+JEE, the deployment step is further refined for each application server.
+See *build.jee.was.xml* and *build.jee.liberty.xml* for build and
+installation steps for WebSphere Application Server and the Liberty Profile
+for WAS, respectively.
+
+Before you run a build, configure the build environment by editing
+*openjpa-examples/openbooks/build.properties*. Essentially, you need to
+
+* Point *openjpa.lib* variable to the local directory where OpenJPA class
+library(ies) reside. Notice that the variable points to a directory and not
+a *\*.jar* file. All *\*.jar* files found under the directory are
+included in compilation classpath. OpenJPA version 2.0, however, is also
+available with all its runtime dependencies (such as JPA specification API,
+Apache Commons Collections and others) packaged together in a _single_
+library (lib).
+
+*Note:&nbsp;* Access to the OpenJPA class libraries is easier if you have a
+Maven repository (.m2) available on your system.&nbsp; In this case, all
+that is required is to update the *openjpa.version* variable to point at
+the proper OpenJPA SNAPSHOT version.
+
+* Ideally, a JPA-compliant application _should_ not require
+provider-specific library during compilation. OpenBooks persistent domain
+model and application logic also does not use any OpenJPA specific
+features, but OpenJPA libraries are still used during compilation because
+bytecode for persistent entities are _enhanced_ as a post-compilation step.
+This bytecode enhancement is not essential but an important step for using
+OpenJPA.
+
+The next step is to configure runtime configuration descriptors and
+environment variables.
+* JSE
+** Edit *persistence.xml* located in
+*openjpa-examples/openbooks/src/main/resources/META-INF* directory.
+Modify the *javax.persistence.jdbc.driver* and
+*javax.persistence.jdbc.url* property to suit your local database and its
+driver.
+** Edit *openjpa-examples/openbooks/run.properties* to specify location
+of OpenJPA class libraries and JDBC Driver used in runtime classpath.  Here
+again, the use of the *openjpa.version* variable with a Maven repository
+makes the library and jdbc driver configuration easy.
+
+* JEE
+** You may already have a JTA data source configured and registered in
+JNDI. Of course, then the appropriate configuration is to be edited
+accordingly in the *<jta-data-source>* and *<non-jta-data-source>*
+clauses. See *persistence.jee.was.xml* for WebSphere environment, or
+*persistence.jee.liberty.xml* for the Liberty Profile. 
+** OpenJPA library and JDBC drivers are configured in JEE server and hence
+variables in this file are irrelevant.
+** More information on the build and installation of the OpenBooks example
+for application servers can be found in the [WebSphere Application Server](#websphere.html)
+ and [Liberty Profile|#liberty]
+ deployment sections.
+
+
+
+Both *build.properties* and *run.properties* files are commented
+in-place on what is to be edited.
+
+
+<a name="BuildingandRunningOpenBooks-BuildOpenBooksfromsource"></a>
+## Build OpenBooks from source
+
+Once you have configured the environment, simply issue (from the
+*openjpa-examples/openbooks* directory):
+
+ *$ ant*
+
+or
+
+ *$ ant \-Dbuild.mode=jee*
+
+The default target of the ant script will
+* generate metamodel classes (required for Criteria API)
+* compile the source code
+* enhance the persistence domain model
+* package the application based on the build.mode as a Swing-based
+application or a Web Application Archive.
+* copy the deployable artifacts to *target* and *target/openbooks*
+directories relative to the current directory.
+
+
+<a name="BuildingandRunningOpenBooks-DeployOpenBooksinanApplicationServer"></a>
+## Deploy OpenBooks in an Application Server
+
+Deployment techniques and configuration vary across JEE compliant
+application servers. Hence, OpenBooks does not provide an uber-deployment
+script for all application server. Instead, application server specific
+steps are encoded in separate build scripts for each application server.
+Using generic build as described in the previous section, the
+*target/openbooks.war* web archive needs to be deployed manually.
+
+{anchor:websphere}
+<a name="BuildingandRunningOpenBooks-WebSphereApplicationServer"></a>
+### WebSphere Application Server
+
+For WebSphere Application Server, automated build scripts are available in
+*build.jee.was.xml*. WebSphere deployment needs to be triggered by
+*ws_ant* utility as follows
+
+ *$ ws_ant \-Dbuild.mode=jee \-Dappserver=was \-Dwas.home=<WAS_HOME>*
+
+where *<WAS_HOME>* denotes the root directory where WAS V7 with JPA 2.0
+feature pack has been installed (at a minimum). Yes, OpenBooks requires
+features defined by the JPA 2.0 specification, thus the use of the WAS V7
+JPA 2.0 feature pack is a minimum requirement. Further information on this
+feature pack is available [here](http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27018836)
+ or [WebSphere in general|http://www-01.ibm.com/software/websphere/]
+.
+
+The WebSphere specific build will configure appropriate JTA data sources
+using a python script (found under *openbooks/scripts/* directory before
+deploying OpenBooks as a web application. The script assumes a single
+server instance. If multiple profiles exist, the script will use the first
+server profile.
+
+{anchor:liberty}
+<a name="BuildingandRunningOpenBooks-LibertyProfileinWebSphereApplicationServerv8.5"></a>
+### Liberty Profile in WebSphere Application Server v8.5
+
+For the Liberty Profile in WebSphere Application Server v8.5, automated
+build scripts are available in *build.jee.liberty.xml*. Liberty Profile
+deployment is very easy and needs to be triggered by *ant* as follows
+
+ {{$ ant \-Dbuild.mode=jee \-Dappserver=liberty
+\-Dliberty.home=<WAS_HOME>/wlp \-Dliberty.server=<server name>}}
+
+where *<WAS_HOME>* denotes the root directory where WAS v8.5 has been
+installed, and <server name> is the name of your Liberty Profile server. 
+Instead of specifying these two variables, *liberty.home* and
+*liberty.server*, you could modify the build variables in the
+*build.jee.liberty.xml* file.  
+
+By specifying *liberty.home* and *liberty.server*, the ant script will
+attempt to "deploy" the resulting openbooks.war application to the
+designated Liberty server.  Additional configuration of your Liberty server
+may be required before OpenBooks will work.  For example, you will need to
+specify the *jpa-2.0* and *jdbc-4.0* features in your server.xml.  You
+will also need to define the JTA datasources used by the OpenBooks
+application via your server.xml file.  Examples of a derby configuration
+can be found in the *openbooks/scripts/liberty* directory.
+
+Additional information on the Liberty Profile can be found [here](http://www.wasdev.net/)
+.  General WebSphere information can be found [here|http://www-01.ibm.com/software/websphere/]
+.
+
+<a name="BuildingandRunningOpenBooks-RunOpenBooks"></a>
+## Run OpenBooks
+
+If you have built OpenBooks for JSE, then go to the
+*openjpa-examples/openbooks/target/openbooks* directory.
+
+Invoke the Ant script to run OpenBooks
+*$ ant \-f run.xml*
+
+
+If you have built OpenBooks for JEE, a Web Application Archive
+*openbooks.war* will be created in *openjpa-examples/openbooks/target*
+directory. You need to deploy *openbooks.war* to a JEE Application
+Server. Once deployed, you can point a browser to Application Server URL
+
+ *http:// < app server host >:<port>/openbooks/*
+
+For example,
+
+ *http://localhost:9080/openbooks/*
+
+to access OpenBooks as a web application.
+
+
+<a name="BuildingandRunningOpenBooks-PopulateOpenBooksDatabase"></a>
+## Populate OpenBooks Database
+
+OpenBooks checks for existing data at first connection to the database. If
+the database is empty, the schema is defined and populated with initial
+data. However, you can explicitly populate the database in JSE build.
+
+*Note:* By default, the OpenBooks example uses and populates an Embedded
+Derby instance on "first touch".  So, no further configuration or loading
+is required for the default configuration.
+
+Edit *load.properties* to specify load parameters such as number of Books
+etc. OpenBooks uses this data to populate a database with some sample data.
+This example file has some typical values. If you are satisfied with it,
+you can leave them as it is. Then invoke the Ant script
+
+ *$ ant \-f run.xml load*

Added: openjpa/site/trunk/content/building.cwiki
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/building.cwiki?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/building.cwiki (added)
+++ openjpa/site/trunk/content/building.cwiki Wed Nov 14 01:49:37 2012
@@ -0,0 +1,401 @@
+{excerpt:hidden=true}How to build OpenJPA from source{excerpt}
+
+h1. Contents
+{toc}
+
+h1. Building OpenJPA
+
+See [Build and Runtime Dependencies] for details on the required Java levels.
+
+h2. Maven
+
+h3. Command Line Builds
+
+These instructions describe how to check out the current OpenJPA source code (from the Subversion source code management repository) and build it (using the Apache Maven 2 build tool). They are written for use from the console, and are known to work on Linux, Mac OSX and Windows.
+
+ # Ensure that you have Java installed and in your path by running: {{java -fullversion}}
+ # Install the build tool, Apache Maven 2.2.1 or later, from http://maven.apache.org/. If it is installed correctly, typing {{mvn -v}} from the console will result in text like {{Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)}}
+ # Install Subversion v1.4.x or newer from http://subversion.apache.org/. If it is installed correctly, typing the following command should output help information: {{svn help}} or {{svn --version}}
+ # Create a new directory you want to do your work in, then change to that directory from the console.
+ # Check out the sources by running: {{svn co https://svn.apache.org/repos/asf/openjpa/trunk openjpa-trunk}}. It will check out the sources to the openjpa-trunk directory. More information on checking out the OpenJPA sources can be found on the [Source Code] page.
+ # Change to the openjpa-trunk directory, which has already been created in the previous step.
+ # Build OpenJPA by running: {{mvn package}} or better {{mvn install}}. The first time you run the build, many dependencies are automatically resolved and downloaded. *It is common for dependency downloading to fail the first time, which will fail the build.* If any of these dependency downloads fail, just re-run the command. You may also add the following to your {{~/.m2/setting.xml}} file (see http://maven.apache.org/guides/mini/guide-mirror-settings.html)
+
+{code:xml}
+<settings>
+    <mirrors>
+        <mirror>
+            <id>repo.mergere.com</id>
+            <url>http://repo.mergere.com/maven2</url>
+            <mirrorOf>central</mirrorOf>
+        </mirror>
+    </mirrors>
+</settings>
+{code}
+
+ If any tests fail, and you want to ignore the failures, instead run:
+
+  {{mvn package -DfailIfNoTests=false}}
+
+ or
+
+  {{mvn package -DskipTests}}
+
+
+An example session is as follows:
+
+{noformat}
+$ cd /tmp/
+
+$ java -version
+
+java version "1.6.0"
+Java(TM) SE Runtime Environment (build 1.6.0-b105)
+Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode, sharing)
+
+$ mvn -v
+
+Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)
+Java version: 1.6.0
+Java home: /alt/sun160/jre
+Default locale: en_US, platform encoding: UTF-8
+OS name: "linux" version: "2.6.18-1.2798.fc6" arch: "i386" Family: "unix"
+
+$ svn --version
+
+svn, version 1.4.3 (r23084)
+   compiled Jan 18 2007, 07:47:40
+
+$ svn co https://svn.apache.org/repos/asf/openjpa/trunk/
+
+A  trunk/openjpa-lib
+A  trunk/openjpa-lib/src
+A  trunk/openjpa-lib/src/test
+A  trunk/openjpa-lib/src/test/java
+A  trunk/openjpa-lib/src/test/java/org
+A  trunk/openjpa-lib/src/test/java/org/apache
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa/lib
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa/lib/test
+A  trunk/openjpa-lib/src/test/java/org/apache/openjpa/lib/test/AbstractTestCase.java
+
+ ...
+
+A  trunk/openjpa-persistence/pom.xml
+Checked out revision 1065345.
+
+$ cd trunk/
+
+$ mvn compile
+
+[INFO] Scanning for projects...
+[INFO] Reactor build order: 
+[INFO]   OpenJPA Parent POM
+[INFO]   OpenJPA Utilities Library
+[INFO]   OpenJPA Kernel
+[INFO]   OpenJPA JDBC
+[INFO]   OpenJPA Persistence
+[INFO]   OpenJPA Persistence JDBC
+[INFO]   OpenJPA Persistence Locking Tests
+[INFO]   OpenJPA XML Store
+[INFO]   OpenJPA Slice
+[INFO]   OpenJPA JEST
+[INFO]   OpenJPA Aggregate Jar
+[INFO]   OpenJPA Aggregate Jar with Dependencies
+[INFO]   OpenJPA Project Docs and Assemblies
+[INFO]   OpenJPA Examples
+[INFO]   OpenJPA Examples - Simple
+[INFO]   OpenJPA Examples - image-gallery
+[INFO]   OpenJPA Examples - OpenBooks
+[INFO]   OpenJPA Integration Tests
+[INFO]   OpenJPA Integration Tests - Daytrader
+[INFO]   OpenJPA Integration Tests - Examples
+[INFO]   OpenJPA Integration Tests - SLF4JLogFactory
+[INFO]   OpenJPA Integration Tests - JPA TCK
+[INFO]   OpenJPA Integration Tests - Bean Validation
+[INFO]   OpenJPA Integration Tests - JMX Platform MBeans
+[INFO] ------------------------------------------------------------------------
+[INFO] Building OpenJPA Parent POM
+[INFO]    task-segment: [compile]
+[INFO] ------------------------------------------------------------------------
+
+ ...
+
+[INFO] 
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO] ------------------------------------------------------------------------
+[INFO] OpenJPA Parent POM .................................... SUCCESS [1:23.143s]
+[INFO] OpenJPA Utilities Library ............................. SUCCESS [13.749s]
+[INFO] OpenJPA Kernel ........................................ SUCCESS [19.251s]
+[INFO] OpenJPA JDBC .......................................... SUCCESS [14.351s]
+[INFO] OpenJPA Persistence ................................... SUCCESS [10.254s]
+[INFO] OpenJPA Persistence JDBC .............................. SUCCESS [46.774s]
+[INFO] OpenJPA Persistence Locking Tests ..................... SUCCESS [15.183s]
+[INFO] OpenJPA XML Store ..................................... SUCCESS [11.788s]
+[INFO] OpenJPA Slice ......................................... SUCCESS [4.437s]
+[INFO] OpenJPA JEST .......................................... SUCCESS [4.854s]
+[INFO] OpenJPA Aggregate Jar ................................. SUCCESS [10.729s]
+[INFO] OpenJPA Aggregate Jar with Dependencies ............... SUCCESS [6.761s]
+[INFO] OpenJPA Project Docs and Assemblies ................... SUCCESS [1:41.937s]
+[INFO] OpenJPA Examples ...................................... SUCCESS [0.663s]
+[INFO] OpenJPA Examples - Simple ............................. SUCCESS [1.475s]
+[INFO] OpenJPA Examples - image-gallery ...................... SUCCESS [3.920s]
+[INFO] OpenJPA Examples - OpenBooks .......................... SUCCESS [12.961s]
+[INFO] OpenJPA Integration Tests ............................. SUCCESS [0.381s]
+[INFO] OpenJPA Integration Tests - Daytrader ................. SUCCESS [7.565s]
+[INFO] OpenJPA Integration Tests - Examples .................. SUCCESS [0.269s]
+[INFO] OpenJPA Integration Tests - SLF4JLogFactory ........... SUCCESS [1.977s]
+[INFO] OpenJPA Integration Tests - JPA TCK ................... SUCCESS [0.248s]
+[INFO] OpenJPA Integration Tests - Bean Validation ........... SUCCESS [3.213s]
+[INFO] OpenJPA Integration Tests - JMX Platform MBeans ....... SUCCESS [7.729s]
+[INFO] ------------------------------------------------------------------------
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 6 minutes 26 seconds
+[INFO] Finished at: Sun Jan 30 19:43:50 CET 2011
+[INFO] Final Memory: 92M/158M
+[INFO] ------------------------------------------------------------------------
+
+
+$ mvn package -DskipTests
+
+[INFO] Scanning for projects...
+
+...
+
+[INFO] Building zip: /tmp/trunk/openjpa-project/target/site/downloads/apache-openjpa-2.2.0-SNAPSHOT-binary.zip
+
+... 
+
+$ ls -lh openjpa-project/target/site/downloads/
+
+total 40M
+-rw-r--r-- 1 milosz milosz 15M Jan 30 19:41 apache-openjpa-2.2.0-SNAPSHOT-binary.zip
+-rw-r--r-- 1 milosz milosz 25M Jan 30 19:43 apache-openjpa-2.2.0-SNAPSHOT-source.zip
+
+{noformat}
+
+
+h3. Executing various Maven build tasks
+
+h5. Running just the "TestPersistence" test case
+
+{noformat}
+mvn test -Dtest=TestPersistence
+{noformat}
+
+h5. Running tests with Java 2 security enabled
+
+{noformat}
+mvn test -Penable-security
+{noformat}
+
+h5. Building and running only the examples included in the distribution
+
+{noformat}
+mvn -DskipTests -Pexamples-profile integration-test
+{noformat}
+
+h5. Building just the javadoc
+
+First install the jars:
+
+{noformat}
+mvn install -DskipTests
+{noformat}
+
+Then build the javadoc:
+
+{noformat}
+mvn package -DskipTests -Pjavadoc-profile
+{noformat}
+
+The javadoc will be output to {{target/site/apidocs/index.html}}.
+
+h5. Building just the docbook documentation
+
+{noformat}
+set MAVEN_OPTS=-Xmx512m
+mvn -f openjpa-project/pom.xml process-resources -Pdocbook-profile
+{noformat}
+
+The manual HTML will be output to {{openjpa-project/target/manual/manual.html}}.
+
+h5. Building with JDK 1.4 module verification (only for versions of OpenJPA prior to svn revision 640685)
+
+{noformat}
+mvn compile -Djava14.jar=C:\Program Files\Java\j2re1.4.2_07\lib\rt.jar compile
+{noformat}
+
+Specifying the "java14.jar" system property will cause the JDK-1.4-dependent modules to be compiled with the value as the bootclasspath to the compiler. This can be useful to ensure that modifications and additions do not violate the JDK version restriction of the module. Since the runtime jar location is platform, version, and installation dependent, the exact location of the runtime jar will vary, which is why it needs to be manually specified.
+
+h2. Eclipse with Command-line Maven utilities
+
+# Checkout the source as described above
+# Build the source using Maven as described above
+# Create the Eclipse Metadata - \\
+{noformat}
+mvn eclipse:eclipse
+{noformat}
+** If this is the first project in your workspace to use maven artifacts you need to create a classpath variable named M2_REPO which contains the full path to your local repository. The eclipse plugin can do this for you with the following command \\
+{noformat}
+mvn eclipse:configure-workspace -Declipse.workspace=${path to your workspace} 
+{noformat}
+# Start Eclipse (3.2 - 3.4 SR2 are known to work) and create a new workspace
+# Import the OpenJPA projects, by:
+** Select File --> Import... --> General - Existing Projects into Workspace --> Next
+** Select root directory = <svn checkout location above>
+** Deselect the openjpa-examples project
+** Press Finish
+# A few fixups will be required to remove the errors that exist in the imported projects...
+** openjpa-kernel -> Properties -> Java Build Path -> Source -> Add Folders
+*** add target/generated-sources/javacc
+** openjpa-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-examples.  Open up src/main/java and select ReverseMapping folder.  Right mouse click.
+*** Select Build Path -> Exclude
+# For each imported project, you'll need to edit the build properties to remove an incorrect dependency:
+** Project --> Properties --> Java Build Path --> Source
+** Remove openjpa-project from the list of source folders
+
+For Java SE 5 users building from the 2.0.x branch, you will need to exclude some Java SE 6 specific classes by performing the following steps for the source:
+# Open the Properties for openjpa-persistence
+# Select Java Build Path --> Source
+# Edit the openjpa-persistence/src/main/java --> Excluded setting to include the following:
+{noformat}
+org/apache/openjpa/persistence/meta/AnnotationProcessor6.java
+org/apache/openjpa/persistence/meta/CompileTimeLogger.java
+org/apache/openjpa/persistence/meta/SourceAnnotationHandler.java
+{noformat}
+
+h2. Eclipse with M2Eclipse plugin
+
+# Checkout the source as described above
+# Build the source using Maven as described above
+# Start Eclipse (3.5 Galileo is recommended) and create a new workspace
+# Good references for this M2Eclipse plugin (need to install the plugin into your Eclipse environment)
+** http://m2eclipse.codehaus.org/
+** http://docs.codehaus.org/display/M2ECLIPSE/Home
+** http://www.theserverside.com/tt/articles/article.tss?l=Introductiontom2eclipse
+# Import the OpenJPA projects, by:
+** Select File --> Import... --> General -> Maven Projects --> Next
+** Select root directory = <svn checkout location above>
+** All of the pom.xml files should be pre-selected for the svn checkout location
+** You can affect the naming convention used for the generated Eclipse projects (one for each Maven module).  Click on Advanced and fill in the Name Template field.  I prefer "TRUNK-\[artifactId\]" since it helps with workspace organization, but it's your choice.
+** Press Finish
+** *Note:*  You may get a popup internal error at the end of this Import processing.  Not sure what the problem is, but it doesn't seem to affect the usage.
+# A few fixups will be required to remove the errors that exist in the imported projects...
+** openjpa-kernel -> Properties -> Java Build Path -> Source -> Add Folders
+*** add target/generated-sources/javacc
+** openjpa-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-persistence-jdbc -> Properties -> Java Build Path -> Libraries -> JRE System Library -> Edit
+*** change this to a Java 6 JRE to remove these errors (see below if you can not use Java SE 6)
+** openjpa-examples.  Open up src/main/java and select ReverseMapping folder.  Right mouse click.
+*** Select Build Path -> Exclude
+
+For Java SE 5 users building from the 2.0.x branch, you will need to exclude some Java SE 6 specific classes by performing the following steps for the source:
+# Open the Properties for BR20-openjpa-persistence (or whatever your naming convention is)
+# Select Java Build Path --> Source
+# Edit the openjpa-persistence/src/main/java --> Excluded setting to include the following:
+{noformat}
+org/apache/openjpa/persistence/meta/AnnotationProcessor6.java
+org/apache/openjpa/persistence/meta/CompileTimeLogger.java
+org/apache/openjpa/persistence/meta/SourceAnnotationHandler.java
+{noformat}
+
+\\
+
+h2. Common 2.x Build Problems
+
+h3. Wrong Maven Level
+
+Example Maven output -
+{code:none}
+[INFO] [enforcer:enforce {execution: default}]
+[WARNING] Rule 0: org.apache.maven.plugins.enforcer.RequireMavenVersion failed with message:
+Detected Maven Version: 2.0.10 is not in the allowed range [2.2.1,).
+[INFO] ------------------------------------------------------------------------
+[ERROR] BUILD ERROR
+[INFO] ------------------------------------------------------------------------
+[INFO] Some Enforcer rules have failed. Look above for specific messages explaining why the rule failed.
+{code}
+Solution - Upgrade to Maven 2.2.1 or later
+
+h3. Wrong Java Level
+
+Example Maven output -
+{code:none}
+[INFO] [enforcer:enforce {execution: default}]
+[WARNING] Rule 1: org.apache.maven.plugins.enforcer.RequireJavaVersion failed with message:
+Detected JDK Version: 1.5.0-19 is not in the allowed range [1.6,).
+[INFO] ------------------------------------------------------------------------
+[ERROR] BUILD ERROR
+[INFO] ------------------------------------------------------------------------
+[INFO] Some Enforcer rules have failed. Look above for specific messages explaining why the rule failed.
+{code}
+Solution - Upgrade to latest Sun JDK 1.6.0 or IBM 6 SDK
+Note - OpenJDK and Java SE 7 are not supported at this time.
+
+h3. Missing License Headers
+
+Example Maven output -
+{code:none}
+. . .
+[INFO] ------------------------------------------------------------------------
+[INFO] Building OpenJPA Parent POM
+[INFO]    task-segment: [clean, install]
+[INFO] ------------------------------------------------------------------------
+. . .
+[INFO] [enforcer:enforce {execution: default}]
+[INFO] [source:test-jar {execution: attach-sources}]
+[INFO] [ianal:verify-legal-files {execution: default}]
+[INFO] [apache-rat:check {execution: default}]
+[INFO] Exclude: **/javax.persistence.spi.PersistenceProvider
+[INFO] Exclude: **/javax.annotation.processing.Processor
+[INFO] Exclude: **/*.rsrc
+[INFO] Exclude: **/org.apache.openjpa.revision.properties
+[INFO] Exclude: scripts/*.list
+[INFO] Exclude: scripts/*.options
+[INFO] Exclude: scripts/*.dict
+[INFO] Exclude: **/.*/**
+[INFO] Exclude: **/target/**/*
+[INFO] Exclude: **/dependency-reduced-pom.xml
+[INFO] Exclude: **/*.log
+[INFO] Exclude: **/maven-eclipse.xml
+[INFO] Exclude: **/rat.txt
+[INFO] Exclude: **/internal-repository/**
+[INFO] ------------------------------------------------------------------------
+[ERROR] BUILD FAILURE
+[INFO] ------------------------------------------------------------------------
+[INFO] Too many unapproved licenses: 1
+[INFO] ------------------------------------------------------------------------
+{code}
+For the module that failed to build (which in the case above is the root pom.xml) open the target/rat.txt file and search for any "????" occurrences, like -
+{code:none}
+. . .
+*****************************************************
+  Files with Apache License headers will be marked AL
+  Binary files (which do not require AL headers) will be marked B
+  Compressed archives will be marked A
+  Notices, licenses etc will be marked N
+  N     LICENSE.txt
+  N     NOTICE.txt
+  AL    openjpa/pom.xml
+  AL    openjpa/src/main/appended-resources/META-INF/LICENSE.vm
+  AL    openjpa/src/main/appended-resources/META-INF/NOTICE.vm
+ !????? OPENJPA-1621.patch
+. . .
+{code}
+Solution - either add the missing ASL 2.0 license header, remove the file from your local working directory (if it is a temporary file that should not be added to svn), or ask on the dev@openjpa list if the file can be added to the exclude list for the apache-rat checks.
+
+
+\\

Propchange: openjpa/site/trunk/content/building.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message