From 77c8d31ee173da8eaaa386c020fe65a6cc2f034b Mon Sep 17 00:00:00 2001
From: Emmanuel Bernard <emmanuel@hibernate.org>
Date: Mon, 14 Feb 2011 19:03:51 +0100
Subject: [PATCH] HHH-5916 Add doc for PersisterClassProvider

---
 .../docbook/en-US/content/configuration.xml   | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/documentation/manual/src/main/docbook/en-US/content/configuration.xml b/documentation/manual/src/main/docbook/en-US/content/configuration.xml
index 8b73de214d..f71a7365da 100644
--- a/documentation/manual/src/main/docbook/en-US/content/configuration.xml
+++ b/documentation/manual/src/main/docbook/en-US/content/configuration.xml
@@ -1347,6 +1347,48 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect</programlisting>
     applications.</para>
   </section>
 
+  <section>
+    <title>Implementing a PersisterClassProvider</title>
+
+    <para>You can configure the persister implementation used to persist your
+    entities and collections:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>by default, Hibernate uses persisters that make sense in a
+        relational model and follow Java Persistence's specification</para>
+      </listitem>
+
+      <listitem>
+        <para>you can define a <classname>PersisterClassProvider</classname>
+        implementation that provides the persister class used of a given
+        entity or collection</para>
+      </listitem>
+
+      <listitem>
+        <para>finally, you can override them on a per entity and collection
+        basis in the mapping using <classname>@Persister</classname> or its
+        XML equivalent</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>The latter in the list the higher in priority.</para>
+
+    <para>You can pass the <classname>PersisterClassProvider</classname>
+    instance to the <classname>Configuration</classname> object.</para>
+
+    <programlisting role="JAVA">SessionFactory sf = new Configuration()
+    .setPersisterClassProvider(customPersisterClassProvider)
+    .addAnnotatedClass(Order.class)
+    .buildSessionFactory();</programlisting>
+
+    <para>The persister class provider methods, when returning a non null
+    persister class, override the default Hibernate persisters. The entity
+    name or the collection role are passed to the methods. It is a nice way to
+    centralize the overriding logic of the persisters instead of spreading
+    them on each entity or collection mapping. </para>
+  </section>
+
   <section id="configuration-xmlconfig" revision="2">
     <title>XML configuration file</title>