From 8d50d567ac4717ad0ad2b23ede1595c9c76ffe48 Mon Sep 17 00:00:00 2001
From: Vlad Mihalcea <mihalcea.vlad@gmail.com>
Date: Tue, 25 Oct 2016 17:41:23 +0300
Subject: [PATCH] HHH-11174 - Document that XML file mappings can reside
 outside of JAR

(cherry picked from commit 8bd6cf6f6babde4db679426ce62dda496bac9b26)
---
 .../chapters/bootstrap/Bootstrap.adoc         | 36 ++++++++++++++++++
 .../bootstrap/extras/persistence-external.xml | 38 +++++++++++++++++++
 .../chapters/domain/basic_types.adoc          |  2 +-
 3 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 documentation/src/main/asciidoc/userguide/chapters/bootstrap/extras/persistence-external.xml

diff --git a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc
index de89d03caa..79d5b15a63 100644
--- a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc
+++ b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc
@@ -82,6 +82,42 @@ http://docs.oracle.com/javaee/7/api/javax/persistence/spi/PersistenceUnitInfo.ht
 https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/HibernatePersistenceProvider.html#createContainerEntityManagerFactory-javax.persistence.spi.PersistenceUnitInfo-java.util.Map-[HibernatePersistenceProvider.html#createContainerEntityManagerFactory].
 ====
 
+[[bootstrap-jpa-xml-files]]
+==== Externalizing XML mapping files
+
+JPA offers two mapping options:
+
+- annotations
+- XML mappings
+
+Although annotations are much more common, there are projects were XML mappings are preferred.
+You can even mix annotations and XML mappings so that you can override annotation mappings with XML configurations that can be easily changed without recompiling the project source code.
+This is possible because if there are two conflicting mappings, the XML mappings takes precedence over its annotation counterpart.
+
+The JPA specifications requires the XML mappings to be located on the class path:
+
+[quote, Section 8.2.1.6.2 of the JPA 2.1 Specification]
+____
+An object/relational mapping XML file named `orm.xml` may be specified in the `META-INF` directory in the root of the persistence unit or in the `META-INF` directory of any jar file referenced by the `persistence.xml`.
+
+Alternatively, or in addition, one or more mapping files may be referenced by the mapping-file elements of the persistence-unit element. These mapping files may be present anywhere on the class path.
+____
+
+Therefore, the mapping files can reside in the application jar artifacts, or they can be stored in an external folder location with the cogitation that that location be included in the class path.
+
+Hibernate is more lenient in this regard so you can use any external location even outside of the application configured class path.
+
+[[bootstrap-jpa-compliant-persistence-xml-external-mappings-example]]
+.META-INF/persistence.xml configuration file for external XML mappings
+====
+[source, JAVA, indent=0]
+----
+include::{extrasdir}/persistence-external.xml[]
+----
+====
+
+In the `persistence.xml` configuration file above, the `orm.xml` XML file containing all JPA entity mappings is located in the `/etc/opt/app/mappings/` folder.
+
 [[bootstrap-native]]
 === Native Bootstrapping
 
diff --git a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/extras/persistence-external.xml b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/extras/persistence-external.xml
new file mode 100644
index 0000000000..e009087fed
--- /dev/null
+++ b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/extras/persistence-external.xml
@@ -0,0 +1,38 @@
+<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
+             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
+             http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
+             version="2.1">
+
+    <persistence-unit name="CRM">
+        <description>
+            Persistence unit for Hibernate User Guide
+        </description>
+
+        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
+
+        <mapping-file>file:///etc/opt/app/mappings/orm.xml</mapping-file>
+
+        <properties>
+            <property name="javax.persistence.jdbc.driver"
+                      value="org.h2.Driver" />
+
+            <property name="javax.persistence.jdbc.url"
+                      value="jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE" />
+
+            <property name="javax.persistence.jdbc.user"
+                      value="sa" />
+
+            <property name="javax.persistence.jdbc.password"
+                      value="" />
+
+            <property name="hibernate.show_sql"
+                      value="true" />
+
+            <property name="hibernate.hbm2ddl.auto"
+                      value="update" />
+        </properties>
+
+    </persistence-unit>
+
+</persistence>
diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc
index 12efbfb924..8ad87fff30 100644
--- a/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc
+++ b/documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc
@@ -1090,7 +1090,7 @@ include::{extrasdir}/basic/basic-auto-quoting-persistence-example.sql[indent=0]
 
 As you can see, both the table name and all the column have been quoted.
 
-For more about quoting-related configuration properties, checkout the <<appendices/Configurations.adoc#configurations-mapping,Mapping configurations>> section as well.
+For more about quoting-related configuration properties, check out the <<appendices/Configurations.adoc#configurations-mapping,Mapping configurations>> section as well.
 
 [[mapping-generated]]
 ==== Generated properties