Extended documentation

ws/Archetypes/mi-maven-archetype-jpa-hibernate/src/main/resources/archetype-resources/Readme.md

-JPA 2 project template
-======================
+Hibernate JPA 2 project template
+================================
 
 General:
 --------
-Executing »`mvn test`« generates metamodel classes being required for
-criteria based queries.
+This project contains:
 
+src/main/resources/META-INF/persistence.xml
+:  Defining two persistence units both offering a JDBC database
+   connection to a Mysql 5 server. You may want to adjust both
+   database type and connection parameters.
 
-Eclipse users:
---------------
-You will have to execute »`mvn test`« manually from the command line or by right
-clicking on your project's root choosing »`Run As`« - - > »`Maven test`«. This will
-trigger the metamodel generating process resolving a compile time error in 
-class »`SearchByIcao`«.
\ No newline at end of file
+:  The first unit will re-create the database schema whereas using
+   the second will preserve your current database schema.
+ 
+Java classes
+: 
+|Class         |Package               |Description           |
+|--------------|----------------------|----------------------|
+|`Airline`     |`$(packageroot)/model`|JPA example entity    |
+|`CreateEntity`|`$(packageroot)`      |Create database schema, persist an instance ofAirline   |
+|`SearchByIcao`|`$(packageroot)`      |JPA typesafe criteria search demo |
+|`EntityTest`  |`$(testroot)`         |Persisting and re-reading an object by primary key value |
+
+src/main/resources/log4j2.xml
+:  Configuring the log4j subsystem.
+
+On executing i.e. »`mvn install`« Maven will generate metamodel
+classes like `Airline_.java` during the »`generate-sources`« phase.
+These classes are being required for
+[typesafe criteria based queries]
+(http://docs.jboss.org/hibernate/entitymanager/3.6/reference/en/html/querycriteria.html#querycriteria-typedquery).
+as being outlined in class `$(packageroot)`/`SearchByIcao`.
+
+Eclipse IDE users:
+------------------
+On initial archetype based project generation your new project's
+class »`SearchByIcao`« reveals a compile time error indicating a
+missing class `Airline_`. Possible resolutions:
+
+* Right click on your project's root choosing 
+»`Run As`« ➩ »`Maven generate-sources`«
+
+* Execute »`mvn generate-sources`« manually from the command line.
+
+This step creates missing metamodel classes thereby resolving the error.
+When working with the Eclipse IDE (rather than with Maven directly)
+this step is required whenever modifying your JPA data model.
+
+IDE problems of this type are due to Eclipse's (and other IDE's)
+limited Maven integration. The above workaroud triggers
+the metamodel generator explicitely.
\ No newline at end of file