Author: steve.ebersole(a)jboss.com Date: 2006-11-07 16:12:32 -0500 (Tue, 07 Nov 2006) New Revision: 10755 Modified: branches/Branch_3_2/Hibernate3/src/org/hibernate/persister/entity/EntityPersister.java Log: started javadocing the persister Modified: branches/Branch_3_2/Hibernate3/src/org/hibernate/persister/entity/EntityPersister.java =================================================================== --- branches/Branch_3_2/Hibernate3/src/org/hibernate/persister/entity/EntityPersister.java 2006-11-07 21:12:19 UTC (rev 10754) +++ branches/Branch_3_2/Hibernate3/src/org/hibernate/persister/entity/EntityPersister.java 2006-11-07 21:12:32 UTC (rev 10755) @@ -20,11 +20,12 @@ import org.hibernate.type.VersionType; /** - * Concrete <tt>EntityPersister</tt>s implement mapping and persistence logic for a particular persistent class. - * <br><br> + * Implementors define mapping and persistence logic for a particular + * strategy of entity mapping. An instance of entity persisters corresponds + * to a given mapped entity. + * <p/> * Implementors must be threadsafe (preferrably immutable) and must provide a constructor - * of type - * <tt>(org.hibernate.map.PersistentClass, org.hibernate.impl.SessionFactoryImplementor)</tt>. + * matching the signature of: {@link org.hibernate.mapping.PersistentClass}, {@link org.hibernate.engine.SessionFactoryImplementor} * * @author Gavin King */ @@ -36,9 +37,12 @@ public static final String ENTITY_ID = "id"; /** - * Finish the initialization of this object, once all <tt>ClassPersisters</tt> have been instantiated. + * Finish the initialization of this object. + * <p/> + * Called only once per {@link org.hibernate.SessionFactory} lifecycle, + * after all entity persisters have been instantiated. * - * Called only once, before any other method. + * @throws org.hibernate.MappingException Indicates an issue in the metdata. */ public void postInstantiate() throws MappingException; @@ -55,129 +59,208 @@ // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ /** - * Returns an object that identifies the space in which identifiers of this class hierarchy are unique. + * Returns an object that identifies the space in which identifiers of + * this entity hierarchy are unique. Might be a table name, a JNDI URL, etc. * - * A table name, a JNDI URL, etc. + * @return The root entity name. */ public String getRootEntityName(); /** - * The classname of the persistent class (used only for messages) + * The entity name which this persister maps. + * + * @return The name of the entity which this persister maps. */ public String getEntityName(); /** - * Is the given entity name the name of a subclass, or this class? + * Determine whether the given name represents a subclass entity + * (or this entity itself) of the entity mapped by this persister. + * + * @param entityName The entity name to be checked. + * @return True if the given entity name represents either the entity + * mapped by this persister or one of its subclass entities; false + * otherwise. */ public boolean isSubclassEntityName(String entityName); /** - * Returns an array of objects that identify spaces in which properties of this class are persisted, - * for instances of this class only. + * Returns an array of objects that identify spaces in which properties of + * this entity are persisted, for instances of this class only. + * <p/> + * For most implementations, this returns the complete set of table names + * to which instances of the mapped entity are persisted (not accounting + * for superclass entity mappings). + * + * @return The property spaces. */ public Serializable[] getPropertySpaces(); /** - * Returns an array of objects that identify spaces in which properties of this class are persisted, - * for instances of this class and its subclasses. + * Returns an array of objects that identify spaces in which properties of + * this entity are persisted, for instances of this class and its subclasses. + * <p/> + * Much like {@link #getPropertySpaces()}, except that here we include subclass + * entity spaces. + * + * @return The query spaces. */ public Serializable[] getQuerySpaces(); /** - * Does this class support dynamic proxies. + * Determine whether this entity supports dynamic proxies. + * + * @return True if the entity has dynamic proxy support; false otherwise. */ public boolean hasProxy(); /** - * Do instances of this class contain collections. + * Determine whether this entity contains references to persistent collections. + * + * @return True if the entity does contain persistent collections; false otherwise. */ public boolean hasCollections(); /** - * Does this entity declare any properties of - * mutable type? + * Determine whether any properties of this entity are considered mutable. + * + * @return True if any properties of the entity are mutable; false otherwise (meaning none are). */ public boolean hasMutableProperties(); /** - * Does this entity own any collections which are - * fetchable by subselect? + * Determine whether this entity contains references to persistent collections + * which are fetchable by subselect? + * + * @return True if the entity contains collections fetchable by subselect; false otherwise. */ public boolean hasSubselectLoadableCollections(); /** - * Does this class declare any cascading save/update/deletes. + * Determine whether this entity has any non-none cascading. + * + * @return True if the entity has any properties with a cscade other than NONE; + * false otherwise (aka, no cascading). */ public boolean hasCascades(); /** - * Are instances of this class mutable. + * Determine whether instances of this entity are considered mutable. + * + * @return True if the entity is considered mutable; false otherwise. */ public boolean isMutable(); /** - * Is this class mapped as a subclass of another class? + * Determine whether the entity is inherited one or more other entities. + * In other words, is this entity a subclass of other entities. + * + * @return True if other entities extend this entity; false otherwise. */ public boolean isInherited(); /** - * Is the identifier assigned before the insert by an <tt>IDGenerator</tt>. Or - * is it returned by the <tt>insert()</tt> method? This determines which form - * of <tt>insert()</tt> will be called. + * Are identifiers of this entity assigned known before the insert execution? + * Or, are they generated (in the database) by the insert execution. + * + * @return True if identifiers for this entity are generated by the insert + * execution. */ public boolean isIdentifierAssignedByInsert(); /** - * Get the type of a particular property + * Get the type of a particular property by name. + * + * @param propertyName The name of the property for which to retrieve + * the typpe. + * @return The type. + * @throws org.hibernate.MappingException Typically indicates an unknown + * property name. */ public Type getPropertyType(String propertyName) throws MappingException; /** - * Compare two snapshots of the state of an instance to determine if the persistent state - * was modified - * @return <tt>null</tt> or the indices of the dirty properties + * Compare the two snapshots to determine if they represent dirty state. + * + * @param currentState The current snapshot + * @param previousState The baseline snapshot + * @param owner The entity containing the state + * @param session The originating session + * @return The indices of all dirty properties, or null if no properties + * were dirty. */ - public int[] findDirty(Object[] x, Object[] y, Object owner, SessionImplementor session) - throws HibernateException; + public int[] findDirty(Object[] currentState, Object[] previousState, Object owner, SessionImplementor session); /** - * Compare the state of an instance to the current database state - * @return <tt>null</tt> or the indices of the dirty properties + * Compare the two snapshots to determine if they represent modified state. + * + * @param old The baseline snapshot + * @param current The current snapshot + * @param object The entity containing the state + * @param session The originating session + * @return The indices of all modified properties, or null if no properties + * were modified. */ - public int[] findModified(Object[] old, Object[] current, Object object, SessionImplementor session) - throws HibernateException; + public int[] findModified(Object[] old, Object[] current, Object object, SessionImplementor session); /** - * Does the class have a property holding the identifier value? + * Determine whether the entity has a particular property holding + * the identifier value. + * + * @return True if the entity has a specific property holding identifier value. */ public boolean hasIdentifierProperty(); + /** - * Do detached instances of this class carry their own identifier value? + * Determine whether detahced instances of this entity carry their own + * identifier value. + * <p/> + * The other option is the deperecated feature where users could supply + * the id during session calls. + * + * @return True if either (1) {@link #hasIdentifierProperty()} or + * (2) the identifier is an embedded composite identifier; false otherwise. */ public boolean canExtractIdOutOfEntity(); /** - * Are instances of this class versioned by a timestamp or version number column. + * Determine whether optimistic locking by column is enabled for this + * entity. + * + * @return True if optimistic locking by column (i.e., <version/> or + * <timestamp/>) is enabled; false otherwise. */ public boolean isVersioned(); /** - * Get the type of versioning (optional operation) + * If {@link #isVersioned()}, then what is the type of the property + * holding the locking value. + * + * @return The type of the version property; or null, if not versioned. */ public VersionType getVersionType(); /** - * Which property holds the version number (optional operation). + * If {@link #isVersioned()}, then what is the index of the property + * holding the locking value. + * + * @return The type of the version property; or -66, if not versioned. */ public int getVersionProperty(); /** - * Does this entity declare a natural id? + * Determine whether this entity defines a natural identifier. + * + * @return True if the entity defines a natural id; false otherwise. */ public boolean hasNaturalIdentifier(); /** - * Which properties hold the natural id? + * If the entity defines a natural id ({@link #hasNaturalIdentifier()}), which + * properties make up the natural id. + * + * @return The indices of the properties making of the natural id; or + * null, if no natural id is defined. */ public int[] getNaturalIdentifierProperties(); @@ -188,15 +271,20 @@ * @param session The session from which the request originated. * @return The natural-id snapshot. */ - public Object[] getNaturalIdentifierSnapshot(Serializable id, SessionImplementor session) throws HibernateException; + public Object[] getNaturalIdentifierSnapshot(Serializable id, SessionImplementor session); /** - * Return the <tt>IdentifierGenerator</tt> for the class + * Determine which identifier generation strategy is used for this entity. + * + * @return The identifier generation strategy. */ - public IdentifierGenerator getIdentifierGenerator() throws HibernateException; + public IdentifierGenerator getIdentifierGenerator(); /** - * Does this entity define some lazy attributes? + * Determine whether this entity defines any lazy properties (ala + * bytecode instrumentation). + * + * @return True if the entity has properties mapped as lazy; false otherwise. */ public boolean hasLazyProperties();