diff --git a/reference/en/modules/persistent_classes.xml b/reference/en/modules/persistent_classes.xml
index 872c8ad542..7991934363 100644
--- a/reference/en/modules/persistent_classes.xml
+++ b/reference/en/modules/persistent_classes.xml
@@ -455,6 +455,72 @@ dynamicSession.close()
in .
+
+
+
+ Tuplizers
+
+
+ org.hibernate.tuple.Tuplizer, and its sub-interfaces, are responsible
+ for managing a particular representation of a piece of data, given that representation's
+ org.hibernate.EntityMode. If a given piece of data is thought of as
+ a data structure, then a tuplizer is the thing which knows how to create such a data structure
+ and how to extract values from and inject values into such a data structure. For example,
+ for the POJO entity mode, the correpsonding tuplizer knows how create the POJO through its
+ constructor and how to access the POJO properties using the defined property accessors.
+ There are two high-level types of Tuplizers, represented by the
+ org.hibernate.tuple.EntityTuplizer and org.hibernate.tuple.ComponentTuplizer
+ interfaces. EntityTuplizers are responsible for managing the above mentioned
+ contracts in regards to entities, while ComponentTuplizers do the same for
+ components.
+
+
+
+ Users may also plug in their own tuplizers. Perhaps you require that a java.util.Map
+ implementation other than java.util.HashMap be used while in the
+ dynamic-map entity-mode; or perhaps you need to define a different proxy generation strategy
+ than the one used by default. Both would be achieved by defining a custom tuplizer
+ implementation. Tuplizers definitions are attached to the entity or component mapping they
+ are meant to manage. Going back to the example of our customer entity:
+
+
+
+
+
+
+
+
+
+
+
+
+ ...
+
+
+
+
+public class CustomMapTuplizerImpl
+ extends org.hibernate.tuple.DynamicMapEntityTuplizer {
+ // override the buildInstantiator() method to plug in our custom map...
+ protected final Instantiator buildInstantiator(
+ org.hibernate.mapping.PersistentClass mappingInfo) {
+ return new CustomMapInstantiator( mappingInfo );
+ }
+
+ private static final class CustomMapInstantiator
+ extends org.hibernate.tuple.DynamicMapInstantitor {
+ // override the generateMap() method to return our custom map...
+ protected final Map generateMap() {
+ return new CustomMap();
+ }
+ }
+}]]>
+
+