org.hibernate.persister.entity
Interface EntityPersister

All Superinterfaces:
OptimisticCacheSource
All Known Subinterfaces:
Loadable, Lockable, OuterJoinLoadable, PostInsertIdentityPersister, Queryable, SQLLoadable, UniqueKeyLoadable
All Known Implementing Classes:
AbstractEntityPersister, JoinedSubclassEntityPersister, SingleTableEntityPersister, UnionSubclassEntityPersister

public interface EntityPersister
extends OptimisticCacheSource

Concrete EntityPersisters implement mapping and persistence logic for a particular persistent class.

Implementors must be threadsafe (preferrably immutable) and must provide a constructor of type (org.hibernate.map.PersistentClass, org.hibernate.impl.SessionFactoryImplementor).

Author:
Gavin King

Field Summary
static String ENTITY_ID
          The property name of the "special" identifier property in HQL
 
Method Summary
 void afterInitialize(Object entity, boolean lazyPropertiesAreUnfetched, SessionImplementor session)
          Called just after the entities properties have been initialized
 void afterReassociate(Object entity, SessionImplementor session)
          Called just after the entity has been reassociated with the session
 boolean canExtractIdOutOfEntity()
          Do detached instances of this class carry their own identifier value?
 Object createProxy(Serializable id, SessionImplementor session)
          Create a new proxy instance
 void delete(Serializable id, Object version, Object object, SessionImplementor session)
          Delete a persistent instance
 int[] findDirty(Object[] x, Object[] y, Object owner, SessionImplementor session)
          Compare two snapshots of the state of an instance to determine if the persistent state was modified
 int[] findModified(Object[] old, Object[] current, Object object, SessionImplementor session)
          Compare the state of an instance to the current database state
 Object forceVersionIncrement(Serializable id, Object currentVersion, SessionImplementor session)
           
 CacheConcurrencyStrategy getCache()
          Get the cache (optional operation)
 CacheEntryStructure getCacheEntryStructure()
          Get the cache structure
 ClassMetadata getClassMetadata()
          Get the user-visible metadata for the class (optional operation)
 Class getConcreteProxyClass(EntityMode entityMode)
          Get the proxy interface that instances of this concrete class will be cast to (optional operation).
 Object getCurrentVersion(Serializable id, SessionImplementor session)
          Get the current version of the object, or return null if there is no row for the given identifier.
 Object[] getDatabaseSnapshot(Serializable id, SessionImplementor session)
          Get the current database state of the object, in a "hydrated" form, without resolving identifiers
 String getEntityName()
          The classname of the persistent class (used only for messages)
 SessionFactoryImplementor getFactory()
          Return the SessionFactory to which this persister "belongs".
 Serializable getIdentifier(Object object, EntityMode entityMode)
          Get the identifier of an instance (throw an exception if no identifier property)
 IdentifierGenerator getIdentifierGenerator()
          Return the IdentifierGenerator for the class
 String getIdentifierPropertyName()
          Get the name of the identifier property (or return null) - need not return the name of an actual Java property
 Type getIdentifierType()
          Get the identifier type
 Class getMappedClass(EntityMode entityMode)
          The persistent class, or null
 int[] getNaturalIdentifierProperties()
          Which properties hold the natural id?
 Object[] getNaturalIdentifierSnapshot(Serializable id, SessionImplementor session)
          Retrieve the current state of the natural-id properties from the database.
 CascadeStyle[] getPropertyCascadeStyles()
          Get the cascade styles of the propertes (optional operation)
 boolean[] getPropertyCheckability()
          Get the "checkability" of the properties of this class (is the property dirty checked, does the cache need to be updated)
 boolean[] getPropertyInsertability()
          Get the "insertability" of the properties of this class (does the property appear in an SQL INSERT)
 boolean[] getPropertyInsertGeneration()
          Which of the properties of this class are database generated values on insert?
 boolean[] getPropertyLaziness()
           
 String[] getPropertyNames()
          Get the names of the class properties - doesn't have to be the names of the actual Java properties (used for XML generation only)
 boolean[] getPropertyNullability()
          Get the nullability of the properties of this class
 Serializable[] getPropertySpaces()
          Returns an array of objects that identify spaces in which properties of this class are persisted, for instances of this class only.
 Type getPropertyType(String propertyName)
          Get the type of a particular property
 Type[] getPropertyTypes()
          Get the Hibernate types of the class properties
 boolean[] getPropertyUpdateability()
          Get the "updateability" of the properties of this class (does the property appear in an SQL UPDATE)
 boolean[] getPropertyUpdateGeneration()
          Which of the properties of this class are database generated values on update?
 Object getPropertyValue(Object object, int i, EntityMode entityMode)
          Get the value of a particular property
 Object getPropertyValue(Object object, String propertyName, EntityMode entityMode)
          Get the value of a particular property
 Object[] getPropertyValues(Object object, EntityMode entityMode)
          Return the (loaded) values of the mapped properties of the object (not including backrefs)
 Object[] getPropertyValuesToInsert(Object object, Map mergeMap, SessionImplementor session)
          Return the values of the insertable properties of the object (including backrefs)
 boolean[] getPropertyVersionability()
          Get the "versionability" of the properties of this class (is the property optimistic-locked)
 Serializable[] getQuerySpaces()
          Returns an array of objects that identify spaces in which properties of this class are persisted, for instances of this class and its subclasses.
 String getRootEntityName()
          Returns an object that identifies the space in which identifiers of this class hierarchy are unique.
 EntityPersister getSubclassEntityPersister(Object instance, SessionFactoryImplementor factory, EntityMode entityMode)
          Get the persister for an instance of this class or a subclass
 Object getVersion(Object object, EntityMode entityMode)
          Get the version number (or timestamp) from the object's version property (or return null if not versioned)
 int getVersionProperty()
          Which property holds the version number (optional operation).
 VersionType getVersionType()
          Get the type of versioning (optional operation)
 EntityMode guessEntityMode(Object object)
          Try to discover the entity mode from the entity instance
 boolean hasCache()
          Does this class have a cache.
 boolean hasCascades()
          Does this class declare any cascading save/update/deletes.
 boolean hasCollections()
          Do instances of this class contain collections.
 boolean hasIdentifierProperty()
          Does the class have a property holding the identifier value?
 boolean hasInsertGeneratedProperties()
          Does this entity define any properties as being database generated on insert?
 boolean hasLazyProperties()
          Does this entity define some lazy attributes?
 boolean hasMutableProperties()
          Does this entity declare any properties of mutable type?
 boolean hasNaturalIdentifier()
          Does this entity declare a natural id?
 boolean hasProxy()
          Does this class support dynamic proxies.
 boolean hasSubselectLoadableCollections()
          Does this entity own any collections which are fetchable by subselect?
 boolean hasUninitializedLazyProperties(Object object, EntityMode entityMode)
          Does the given instance have any uninitialized lazy properties?
 boolean hasUpdateGeneratedProperties()
          Does this entity define any properties as being database generated on update?
 boolean implementsLifecycle(EntityMode entityMode)
          Does the class implement the Lifecycle interface.
 boolean implementsValidatable(EntityMode entityMode)
          Does the class implement the Validatable interface.
 Serializable insert(Object[] fields, Object object, SessionImplementor session)
          Persist an instance, using a natively generated identifier (optional operation)
 void insert(Serializable id, Object[] fields, Object object, SessionImplementor session)
          Persist an instance
 Object instantiate(Serializable id, EntityMode entityMode)
          Create a class instance initialized with the given identifier
 boolean isBatchLoadable()
          Is batch loading enabled?
 boolean isCacheInvalidationRequired()
          Should we always invalidate the cache instead of recaching updated state
 boolean isIdentifierAssignedByInsert()
          Is the identifier assigned before the insert by an IDGenerator.
 boolean isInherited()
          Is this class mapped as a subclass of another class?
 boolean isInstance(Object object, EntityMode entityMode)
          Is the given object an instance of this entity?
 boolean isInstrumented(EntityMode entityMode)
          Has the class actually been bytecode instrumented?
 boolean isLazyPropertiesCacheable()
          Should lazy properties of this entity be cached?
 boolean isMutable()
          Are instances of this class mutable.
 boolean isSelectBeforeUpdateRequired()
          Is select snapshot before update enabled?
 boolean isSubclassEntityName(String entityName)
          Is the given entity name the name of a subclass, or this class?
 Boolean isTransient(Object object, SessionImplementor session)
          Is this a new transient instance?
 boolean isVersioned()
          Are instances of this class versioned by a timestamp or version number column.
 boolean isVersionPropertyGenerated()
          Does this entity contain a version property that is defined to be database generated?
 Object load(Serializable id, Object optionalObject, LockMode lockMode, SessionImplementor session)
          Load an instance of the persistent class.
 void lock(Serializable id, Object version, Object object, LockMode lockMode, SessionImplementor session)
          Do a version check (optional operation)
 void postInstantiate()
          Finish the initialization of this object, once all ClassPersisters have been instantiated.
 void processInsertGeneratedProperties(Serializable id, Object entity, Object[] state, SessionImplementor session)
          Perform a select to retrieve the values of any generated properties back from the database, injecting these generated values into the given entity as well as writing this state to the PersistenceContext.
 void processUpdateGeneratedProperties(Serializable id, Object entity, Object[] state, SessionImplementor session)
          Perform a select to retrieve the values of any generated properties back from the database, injecting these generated values into the given entity as well as writing this state to the PersistenceContext.
 void resetIdentifier(Object entity, Serializable currentId, Object currentVersion, EntityMode entityMode)
          Set the identifier and version of the given instance back to its "unsaved" value, returning the id
 void setIdentifier(Object object, Serializable id, EntityMode entityMode)
          Set the identifier of an instance (or do nothing if no identifier property)
 void setPropertyValue(Object object, int i, Object value, EntityMode entityMode)
          Set the value of a particular property
 void setPropertyValues(Object object, Object[] values, EntityMode entityMode)
          Set the given values to the mapped properties of the given object
 void update(Serializable id, Object[] fields, int[] dirtyFields, boolean hasDirtyCollection, Object[] oldFields, Object oldVersion, Object object, Object rowId, SessionImplementor session)
          Update a persistent instance
 
Methods inherited from interface org.hibernate.cache.OptimisticCacheSource
getVersionComparator
 

Field Detail

ENTITY_ID

static final String ENTITY_ID
The property name of the "special" identifier property in HQL

See Also:
Constant Field Values
Method Detail

postInstantiate

void postInstantiate()
                     throws MappingException
Finish the initialization of this object, once all ClassPersisters have been instantiated. Called only once, before any other method.

Throws:
MappingException

getFactory

SessionFactoryImplementor getFactory()
Return the SessionFactory to which this persister "belongs".

Returns:
The owning SessionFactory.

getRootEntityName

String getRootEntityName()
Returns an object that identifies the space in which identifiers of this class hierarchy are unique. A table name, a JNDI URL, etc.


getEntityName

String getEntityName()
The classname of the persistent class (used only for messages)


isSubclassEntityName

boolean isSubclassEntityName(String entityName)
Is the given entity name the name of a subclass, or this class?


getPropertySpaces

Serializable[] getPropertySpaces()
Returns an array of objects that identify spaces in which properties of this class are persisted, for instances of this class only.


getQuerySpaces

Serializable[] getQuerySpaces()
Returns an array of objects that identify spaces in which properties of this class are persisted, for instances of this class and its subclasses.


hasProxy

boolean hasProxy()
Does this class support dynamic proxies.


hasCollections

boolean hasCollections()
Do instances of this class contain collections.


hasMutableProperties

boolean hasMutableProperties()
Does this entity declare any properties of mutable type?


hasSubselectLoadableCollections

boolean hasSubselectLoadableCollections()
Does this entity own any collections which are fetchable by subselect?


hasCascades

boolean hasCascades()
Does this class declare any cascading save/update/deletes.


isMutable

boolean isMutable()
Are instances of this class mutable.


isInherited

boolean isInherited()
Is this class mapped as a subclass of another class?


isIdentifierAssignedByInsert

boolean isIdentifierAssignedByInsert()
Is the identifier assigned before the insert by an IDGenerator. Or is it returned by the insert() method? This determines which form of insert() will be called.


getPropertyType

Type getPropertyType(String propertyName)
                     throws MappingException
Get the type of a particular property

Throws:
MappingException

findDirty

int[] findDirty(Object[] x,
                Object[] y,
                Object owner,
                SessionImplementor session)
                throws HibernateException
Compare two snapshots of the state of an instance to determine if the persistent state was modified

Returns:
null or the indices of the dirty properties
Throws:
HibernateException

findModified

int[] findModified(Object[] old,
                   Object[] current,
                   Object object,
                   SessionImplementor session)
                   throws HibernateException
Compare the state of an instance to the current database state

Returns:
null or the indices of the dirty properties
Throws:
HibernateException

hasIdentifierProperty

boolean hasIdentifierProperty()
Does the class have a property holding the identifier value?


canExtractIdOutOfEntity

boolean canExtractIdOutOfEntity()
Do detached instances of this class carry their own identifier value?


isVersioned

boolean isVersioned()
Are instances of this class versioned by a timestamp or version number column.

Specified by:
isVersioned in interface OptimisticCacheSource
Returns:
True if this source represents versioned data; false otherwise.

getVersionType

VersionType getVersionType()
Get the type of versioning (optional operation)


getVersionProperty

int getVersionProperty()
Which property holds the version number (optional operation).


hasNaturalIdentifier

boolean hasNaturalIdentifier()
Does this entity declare a natural id?


getNaturalIdentifierProperties

int[] getNaturalIdentifierProperties()
Which properties hold the natural id?


getNaturalIdentifierSnapshot

Object[] getNaturalIdentifierSnapshot(Serializable id,
                                      SessionImplementor session)
                                      throws HibernateException
Retrieve the current state of the natural-id properties from the database.

Parameters:
id - The identifier of the entity for which to retrieve the naturak-id values.
session - The session from which the request originated.
Returns:
The natural-id snapshot.
Throws:
HibernateException

getIdentifierGenerator

IdentifierGenerator getIdentifierGenerator()
                                           throws HibernateException
Return the IdentifierGenerator for the class

Throws:
HibernateException

hasLazyProperties

boolean hasLazyProperties()
Does this entity define some lazy attributes?


load

Object load(Serializable id,
            Object optionalObject,
            LockMode lockMode,
            SessionImplementor session)
            throws HibernateException
Load an instance of the persistent class.

Throws:
HibernateException

lock

void lock(Serializable id,
          Object version,
          Object object,
          LockMode lockMode,
          SessionImplementor session)
          throws HibernateException
Do a version check (optional operation)

Throws:
HibernateException

insert

void insert(Serializable id,
            Object[] fields,
            Object object,
            SessionImplementor session)
            throws HibernateException
Persist an instance

Throws:
HibernateException

insert

Serializable insert(Object[] fields,
                    Object object,
                    SessionImplementor session)
                    throws HibernateException
Persist an instance, using a natively generated identifier (optional operation)

Throws:
HibernateException

delete

void delete(Serializable id,
            Object version,
            Object object,
            SessionImplementor session)
            throws HibernateException
Delete a persistent instance

Throws:
HibernateException

update

void update(Serializable id,
            Object[] fields,
            int[] dirtyFields,
            boolean hasDirtyCollection,
            Object[] oldFields,
            Object oldVersion,
            Object object,
            Object rowId,
            SessionImplementor session)
            throws HibernateException
Update a persistent instance

Throws:
HibernateException

getPropertyTypes

Type[] getPropertyTypes()
Get the Hibernate types of the class properties


getPropertyNames

String[] getPropertyNames()
Get the names of the class properties - doesn't have to be the names of the actual Java properties (used for XML generation only)


getPropertyInsertability

boolean[] getPropertyInsertability()
Get the "insertability" of the properties of this class (does the property appear in an SQL INSERT)


getPropertyInsertGeneration

boolean[] getPropertyInsertGeneration()
Which of the properties of this class are database generated values on insert?


getPropertyUpdateGeneration

boolean[] getPropertyUpdateGeneration()
Which of the properties of this class are database generated values on update?


getPropertyUpdateability

boolean[] getPropertyUpdateability()
Get the "updateability" of the properties of this class (does the property appear in an SQL UPDATE)


getPropertyCheckability

boolean[] getPropertyCheckability()
Get the "checkability" of the properties of this class (is the property dirty checked, does the cache need to be updated)


getPropertyNullability

boolean[] getPropertyNullability()
Get the nullability of the properties of this class


getPropertyVersionability

boolean[] getPropertyVersionability()
Get the "versionability" of the properties of this class (is the property optimistic-locked)


getPropertyLaziness

boolean[] getPropertyLaziness()

getPropertyCascadeStyles

CascadeStyle[] getPropertyCascadeStyles()
Get the cascade styles of the propertes (optional operation)


getIdentifierType

Type getIdentifierType()
Get the identifier type


getIdentifierPropertyName

String getIdentifierPropertyName()
Get the name of the identifier property (or return null) - need not return the name of an actual Java property


isCacheInvalidationRequired

boolean isCacheInvalidationRequired()
Should we always invalidate the cache instead of recaching updated state


isLazyPropertiesCacheable

boolean isLazyPropertiesCacheable()
Should lazy properties of this entity be cached?


hasCache

boolean hasCache()
Does this class have a cache.


getCache

CacheConcurrencyStrategy getCache()
Get the cache (optional operation)


getCacheEntryStructure

CacheEntryStructure getCacheEntryStructure()
Get the cache structure


getClassMetadata

ClassMetadata getClassMetadata()
Get the user-visible metadata for the class (optional operation)


isBatchLoadable

boolean isBatchLoadable()
Is batch loading enabled?


isSelectBeforeUpdateRequired

boolean isSelectBeforeUpdateRequired()
Is select snapshot before update enabled?


getDatabaseSnapshot

Object[] getDatabaseSnapshot(Serializable id,
                             SessionImplementor session)
                             throws HibernateException
Get the current database state of the object, in a "hydrated" form, without resolving identifiers

Returns:
null if there is no row in the database
Throws:
HibernateException

getCurrentVersion

Object getCurrentVersion(Serializable id,
                         SessionImplementor session)
                         throws HibernateException
Get the current version of the object, or return null if there is no row for the given identifier. In the case of unversioned data, return any object if the row exists.

Throws:
HibernateException

forceVersionIncrement

Object forceVersionIncrement(Serializable id,
                             Object currentVersion,
                             SessionImplementor session)
                             throws HibernateException
Throws:
HibernateException

guessEntityMode

EntityMode guessEntityMode(Object object)
Try to discover the entity mode from the entity instance


isInstrumented

boolean isInstrumented(EntityMode entityMode)
Has the class actually been bytecode instrumented?


hasInsertGeneratedProperties

boolean hasInsertGeneratedProperties()
Does this entity define any properties as being database generated on insert?

Returns:
True if this entity contains at least one property defined as generated (including version property, but not identifier).

hasUpdateGeneratedProperties

boolean hasUpdateGeneratedProperties()
Does this entity define any properties as being database generated on update?

Returns:
True if this entity contains at least one property defined as generated (including version property, but not identifier).

isVersionPropertyGenerated

boolean isVersionPropertyGenerated()
Does this entity contain a version property that is defined to be database generated?

Returns:
true if this entity contains a version property and that property has been marked as generated.

afterInitialize

void afterInitialize(Object entity,
                     boolean lazyPropertiesAreUnfetched,
                     SessionImplementor session)
Called just after the entities properties have been initialized


afterReassociate

void afterReassociate(Object entity,
                      SessionImplementor session)
Called just after the entity has been reassociated with the session


createProxy

Object createProxy(Serializable id,
                   SessionImplementor session)
                   throws HibernateException
Create a new proxy instance

Throws:
HibernateException

isTransient

Boolean isTransient(Object object,
                    SessionImplementor session)
                    throws HibernateException
Is this a new transient instance?

Throws:
HibernateException

getPropertyValuesToInsert

Object[] getPropertyValuesToInsert(Object object,
                                   Map mergeMap,
                                   SessionImplementor session)
                                   throws HibernateException
Return the values of the insertable properties of the object (including backrefs)

Throws:
HibernateException

processInsertGeneratedProperties

void processInsertGeneratedProperties(Serializable id,
                                      Object entity,
                                      Object[] state,
                                      SessionImplementor session)
Perform a select to retrieve the values of any generated properties back from the database, injecting these generated values into the given entity as well as writing this state to the PersistenceContext.

Note, that because we update the PersistenceContext here, callers need to take care that they have already written the initial snapshot to the PersistenceContext before calling this method.

Parameters:
id - The entity's id value.
entity - The entity for which to get the state.
state -
session - The session

processUpdateGeneratedProperties

void processUpdateGeneratedProperties(Serializable id,
                                      Object entity,
                                      Object[] state,
                                      SessionImplementor session)
Perform a select to retrieve the values of any generated properties back from the database, injecting these generated values into the given entity as well as writing this state to the PersistenceContext.

Note, that because we update the PersistenceContext here, callers need to take care that they have already written the initial snapshot to the PersistenceContext before calling this method.

Parameters:
id - The entity's id value.
entity - The entity for which to get the state.
state -
session - The session

getMappedClass

Class getMappedClass(EntityMode entityMode)
The persistent class, or null


implementsLifecycle

boolean implementsLifecycle(EntityMode entityMode)
Does the class implement the Lifecycle interface.


implementsValidatable

boolean implementsValidatable(EntityMode entityMode)
Does the class implement the Validatable interface.


getConcreteProxyClass

Class getConcreteProxyClass(EntityMode entityMode)
Get the proxy interface that instances of this concrete class will be cast to (optional operation).


setPropertyValues

void setPropertyValues(Object object,
                       Object[] values,
                       EntityMode entityMode)
                       throws HibernateException
Set the given values to the mapped properties of the given object

Throws:
HibernateException

setPropertyValue

void setPropertyValue(Object object,
                      int i,
                      Object value,
                      EntityMode entityMode)
                      throws HibernateException
Set the value of a particular property

Throws:
HibernateException

getPropertyValues

Object[] getPropertyValues(Object object,
                           EntityMode entityMode)
                           throws HibernateException
Return the (loaded) values of the mapped properties of the object (not including backrefs)

Throws:
HibernateException

getPropertyValue

Object getPropertyValue(Object object,
                        int i,
                        EntityMode entityMode)
                        throws HibernateException
Get the value of a particular property

Throws:
HibernateException

getPropertyValue

Object getPropertyValue(Object object,
                        String propertyName,
                        EntityMode entityMode)
                        throws HibernateException
Get the value of a particular property

Throws:
HibernateException

getIdentifier

Serializable getIdentifier(Object object,
                           EntityMode entityMode)
                           throws HibernateException
Get the identifier of an instance (throw an exception if no identifier property)

Throws:
HibernateException

setIdentifier

void setIdentifier(Object object,
                   Serializable id,
                   EntityMode entityMode)
                   throws HibernateException
Set the identifier of an instance (or do nothing if no identifier property)

Throws:
HibernateException

getVersion

Object getVersion(Object object,
                  EntityMode entityMode)
                  throws HibernateException
Get the version number (or timestamp) from the object's version property (or return null if not versioned)

Throws:
HibernateException

instantiate

Object instantiate(Serializable id,
                   EntityMode entityMode)
                   throws HibernateException
Create a class instance initialized with the given identifier

Throws:
HibernateException

isInstance

boolean isInstance(Object object,
                   EntityMode entityMode)
Is the given object an instance of this entity?


hasUninitializedLazyProperties

boolean hasUninitializedLazyProperties(Object object,
                                       EntityMode entityMode)
Does the given instance have any uninitialized lazy properties?


resetIdentifier

void resetIdentifier(Object entity,
                     Serializable currentId,
                     Object currentVersion,
                     EntityMode entityMode)
Set the identifier and version of the given instance back to its "unsaved" value, returning the id

Parameters:
currentId - TODO
currentVersion - TODO

getSubclassEntityPersister

EntityPersister getSubclassEntityPersister(Object instance,
                                           SessionFactoryImplementor factory,
                                           EntityMode entityMode)
Get the persister for an instance of this class or a subclass