[hibernate-commits] Hibernate SVN: r10755 - branches/Branch_3_2/Hibernate3/src/org/hibernate/persister/entity
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Nov 7 16:12:33 EST 2006
Author: steve.ebersole at 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();
More information about the hibernate-commits
mailing list