HHH-11174 - Document that XML file mappings can reside outside of JAR

(cherry picked from commit 8bd6cf6f6b)

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
 

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>

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