[hibernate-commits] Hibernate SVN: r15933 - core/branches/Branch_3_2/doc/reference/en/modules.

Author: steve.ebersole(a)jboss.com Date: 2009-02-10 16:45:05 -0500 (Tue, 10 Feb 2009) New Revision: 15933 Modified: core/branches/Branch_3_2/doc/reference/en/modules/persistent_classes.xml Log: HHH-3760 : document EntityNameResolver Modified: core/branches/Branch_3_2/doc/reference/en/modules/persistent_classes.xml =================================================================== --- core/branches/Branch_3_2/doc/reference/en/modules/persistent_classes.xml 2009-02-10 21:44:48 UTC (rev 15932) +++ core/branches/Branch_3_2/doc/reference/en/modules/persistent_classes.xml 2009-02-10 21:45:05 UTC (rev 15933) @@ -1,3 +1,5 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + <chapter id="persistent-classes" revision="2"> <title>Persistent Classes</title> @@ -523,6 +525,153 @@ </sect1> + <sect1 id="persistent-classes-entity-name-resolver" revision="0"> + <title>EntityNameResolvers</title> + + <para> + The <interfacename>org.hibernate.EntityNameResolver</interfacename> interface is a contract for resolving the + entity name of a given entity instance. The interface defines a single method <methodname>resolveEntityName</methodname> + which is passed the entity instance and is expected to return the appropriate entity name (null is allowed and + would indicate that the resolver does not know how to resolve the entity name of the given entity instance). + Generally speaking, an <interfacename>org.hibernate.EntityNameResolver</interfacename> is going to be most + useful in the case of dynamic models. One example might be using proxied interfaces as your domain model. The + hibernate test suite has an example of this exact style of usage under the + <package>org.hibernate.test.dynamicentity.tuplizer2</package>. Here is some of the code from that package + for illustration. + </para> + + <programlisting> +/** + * A very trivial JDK Proxy InvocationHandler implementation where we proxy an interface as + * the domain model and simply store persistent state in an internal Map. This is an extremely + * trivial example meant only for illustration. + */ +public final class DataProxyHandler implements InvocationHandler { + private String entityName; + private HashMap data = new HashMap(); + + public DataProxyHandler(String entityName, Serializable id) { + this.entityName = entityName; + data.put( "Id", id ); + } + + public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { + String methodName = method.getName(); + if ( methodName.startsWith( "set" ) ) { + String propertyName = methodName.substring( 3 ); + data.put( propertyName, args[0] ); + } + else if ( methodName.startsWith( "get" ) ) { + String propertyName = methodName.substring( 3 ); + return data.get( propertyName ); + } + else if ( "toString".equals( methodName ) ) { + return entityName + "#" + data.get( "Id" ); + } + else if ( "hashCode".equals( methodName ) ) { + return new Integer( this.hashCode() ); + } + return null; + } + + public String getEntityName() { + return entityName; + } + + public HashMap getData() { + return data; + } +} + +/** + * + */ +public class ProxyHelper { + public static String extractEntityName(Object object) { + // Our custom java.lang.reflect.Proxy instances actually bundle + // their appropriate entity name, so we simply extract it from there + // if this represents one of our proxies; otherwise, we return null + if ( Proxy.isProxyClass( object.getClass() ) ) { + InvocationHandler handler = Proxy.getInvocationHandler( object ); + if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) { + DataProxyHandler myHandler = ( DataProxyHandler ) handler; + return myHandler.getEntityName(); + } + } + return null; + } + + // various other utility methods .... + +} + +/** + * The EntityNameResolver implementation. + * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names should be + * resolved. Since this particular impl can handle resolution for all of our entities we want to + * take advantage of the fact that SessionFactoryImpl keeps these in a Set so that we only ever + * have one instance registered. Why? Well, when it comes time to resolve an entity name, + * Hibernate must iterate over all the registered resolvers. So keeping that number down + * helps that process be as speedy as possible. Hence the equals and hashCode impls + */ +public class MyEntityNameResolver implements EntityNameResolver { + public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver(); + + public String resolveEntityName(Object entity) { + return ProxyHelper.extractEntityName( entity ); + } + + public boolean equals(Object obj) { + return getClass().equals( obj.getClass() ); + } + + public int hashCode() { + return getClass().hashCode(); + } +} + +public class MyEntityTuplizer extends PojoEntityTuplizer { + public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) { + super( entityMetamodel, mappedEntity ); + } + + public EntityNameResolver[] getEntityNameResolvers() { + return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE }; + } + + public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) { + String entityName = ProxyHelper.extractEntityName( entityInstance ); + if ( entityName == null ) { + entityName = super.determineConcreteSubclassEntityName( entityInstance, factory ); + } + return entityName; + } + + ... +} + </programlisting> + + <para> + In order to register an <interfacename>org.hibernate.EntityNameResolver</interfacename> users must either: + <orderedlist> + <listitem> + <para> + Implement a custom <link linkend="persistent-classes-tuplizers">Tuplizer</link>, implementing + the <methodname>getEntityNameResolvers</methodname> method. + </para> + </listitem> + <listitem> + <para> + Register it with the <classname>org.hibernate.impl.SessionFactoryImpl</classname> (which is the + implementation class for <interfacename>org.hibernate.SessionFactory</interfacename>) using the + <methodname>registerEntityNameResolver</methodname> method. + </para> + </listitem> + </orderedlist> + </para> + </sect1> + + <para> TODO: Document user-extension framework in the property and proxy packages </para>