Class CollectionType
- java.lang.Object
- org.hibernate.type.AbstractType
- org.hibernate.type.CollectionType
- All Implemented Interfaces:
Serializable,AssociationType,Type
- Direct Known Subclasses:
ArrayType,BagType,CustomCollectionType,IdentifierBagType,ListType,MapType,SetType
public abstract classCollectionTypeextendsAbstractTypeimplementsAssociationType
A type that handles HibernatePersistentCollections (including arrays).- See Also:
- Serialized Form
Field Summary
Fields Modifier and Type Field Description staticObjectUNFETCHED_COLLECTIONFields inherited from class org.hibernate.type.AbstractType
LEGACY_DEFAULT_SIZE,LEGACY_DICTATED_SIZE
Constructor Summary
Constructors Constructor Description CollectionType(String role,String foreignKeyPropertyName)
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description Objectassemble(Serializable cached,SharedSessionContractImplementor session,Object owner)Reconstruct the object from its disassembled state.intcompare(Object x,Object y)Perform aComparator-style comparison of the given values.intcompare(Object x,Object y,SessionFactoryImplementor sessionFactory)booleancontains(Object collection,Object childObject,SharedSessionContractImplementor session)ObjectdeepCopy(Object value,SessionFactoryImplementor factory)Return a deep copy of the persistent state, stopping at entities and at collections.Serializabledisassemble(Object value,SessionFactoryImplementor sessionFactory)Return a disassembled representation of the object.Serializabledisassemble(Object value,SharedSessionContractImplementor session,Object owner)Return a disassembled representation of the object.StringgetAssociatedEntityName(SessionFactoryImplementor factory)Get the entity name of the associated entityJoinablegetAssociatedJoinable(SessionFactoryImplementor factory)Get the "persister" for this association - a class or collection persisterObjectgetCollection(Object key,SharedSessionContractImplementor session,Object owner,Boolean overridingEager)instantiate a collection wrapper (called when loading an object)abstractCollectionClassificationgetCollectionClassification()intgetColumnSpan(Mapping session)How many columns are used to persist this type?Iterator<?>getElementsIterator(Object collection)Get an iterator over the element set of the collection, which may not yet be wrappedIterator<?>getElementsIterator(Object collection,SharedSessionContractImplementor session)Deprecated.TypegetElementType(SessionFactoryImplementor factory)Get the Hibernate type of the collection elementsForeignKeyDirectiongetForeignKeyDirection()Get the foreign key directionality of this associationintgetHashCode(Object x)Get a hash code, consistent with persistence "equality".ObjectgetIdOfOwnerOrNull(Object key,SharedSessionContractImplementor session)Get the id value from the owning entity key, usually the same as the key, but might be some other property, in the case of property-ref@NullableObjectgetKeyOfOwner(Object owner,SharedSessionContractImplementor session)Get the key value from the owning entity instance, usually the identifier, but might be some other unique key, in the case of property-refStringgetLHSPropertyName()Get the name of a property in the owning entity that provides the join key (null if the identifier)StringgetName()Returns the abbreviated name of the type.StringgetRHSUniqueKeyPropertyName()The name of a unique property of the associated entity that provides the join key (null if the identifier of an entity, or key of a collection)StringgetRole()int[]getSqlTypeCodes(Mapping session)booleanhasHolder()ObjectindexOf(Object collection,Object element)protected booleaninitializeImmediately()abstractObjectinstantiate(int anticipatedSize)Instantiate an empty instance of the "underlying" collection (not a wrapper), but with the given anticipated size (i.e.abstractPersistentCollection<?>instantiate(SharedSessionContractImplementor session,CollectionPersister persister,Object key)Instantiate an uninitialized collection wrapper or holder.protectedObjectinstantiateResult(Object original)Instantiate a new "underlying" collection exhibiting the same capacity characteristics and the passed "original".booleanisAlwaysDirtyChecked()We always need to dirty check the collection because we sometimes need to increment version number of owner and also because of how assemble/disassemble is implemented for uksbooleanisArrayType()booleanisAssociationType()Note: return true because this type is castable toAssociationType.booleanisCollectionType()Return true if the implementation is castable toCollectionType.booleanisDirty(Object old,Object current, boolean[] checkable,SharedSessionContractImplementor session)Should the parent be considered dirty, given both the old and current value?booleanisDirty(Object old,Object current,SharedSessionContractImplementor session)Should the parent be considered dirty, given both the old and current value?booleanisEqual(Object x,Object y)Compare two instances of the class mapped by this type for persistence "equality", that is, equality of persistent state.booleanisInverse(SessionFactoryImplementor factory)booleanisModified(Object old,Object current, boolean[] checkable,SharedSessionContractImplementor session)Has the value been modified compared to the current database state? The difference between this and theType.isDirty(java.lang.Object, java.lang.Object, org.hibernate.engine.spi.SharedSessionContractImplementor)methods is that here we need to account for "partially" built values.booleanisMutable()Are objects of this type mutable with respect to the referencing object? Entities and collections are considered immutable because they manage their own internal state.voidnullSafeSet(PreparedStatement st,Object value, int index, boolean[] settable,SharedSessionContractImplementor session)Bind a value represented by an instance of themapped classto the given JDBCPreparedStatement, ignoring some columns as dictated by thesettableparameter.voidnullSafeSet(PreparedStatement st,Object value, int index,SharedSessionContractImplementor session)Bind a value represented by an instance of themapped classto the given JDBCPreparedStatement, ignoring some columns as dictated by thesettableparameter.protectedStringrenderLoggableString(Object value,SessionFactoryImplementor factory)Objectreplace(Object original,Object target,SharedSessionContractImplementor session,Object owner,Map<Object,Object> copyCache)During merge, replace the existing (target) value in the entity we are merging to with a new (original) value from the detached entity we are merging.ObjectreplaceElements(Object original,Object target,Object owner,Map<Object,Object> copyCache,SharedSessionContractImplementor session)Replace the elements of a collection with the elements of another collection.boolean[]toColumnNullness(Object value,Mapping mapping)Given an instance of the type, return an array ofbooleanvalues indicating which mapped columns would be null.StringtoLoggableString(Object value,SessionFactoryImplementor factory)Generate a representation of the given value for logging purposes.StringtoString()booleanuseLHSPrimaryKey()Is the primary key of the owning entity table to be used in the join?abstractPersistentCollection<?>wrap(SharedSessionContractImplementor session,Object collection)Wrap the naked collection instance in a wrapper, or instantiate a holder.Methods inherited from class org.hibernate.type.AbstractType
beforeAssemble,getHashCode,isAnyType,isComponentType,isEntityType,isEqual,isSame,replace
Methods inherited from class java.lang.Object
clone,equals,finalize,getClass,hashCode,notify,notifyAll,wait,wait,wait
Methods inherited from interface org.hibernate.type.Type
beforeAssemble,getHashCode,getReturnedClass,getReturnedClassName,getTypeForEqualsHashCode,isAnyType,isComponentType,isEntityType,isEqual,isSame,replace
Method Detail
getCollectionClassification
public abstract CollectionClassification getCollectionClassification()
getRole
public String getRole()
contains
public boolean contains(Object collection,Object childObject,SharedSessionContractImplementor session)
isCollectionType
public boolean isCollectionType()
Description copied from interface:TypeReturn true if the implementation is castable toCollectionType. Shortcut fortype instanceof CollectionTypeA
CollectionTypeis additionally anAssociationType; so if this method returns true,Type.isAssociationType()should also return true.- Specified by:
isCollectionTypein interfaceType- Overrides:
isCollectionTypein classAbstractType- Returns:
- True if this type is also a
CollectionTypeimplementor; false otherwise.
isEqual
public final boolean isEqual(Object x,Object y)
Description copied from interface:TypeCompare two instances of the class mapped by this type for persistence "equality", that is, equality of persistent state. For most types this could simply delegate toequals().This should always equate to some form of comparison of the value's internal state. As an example, for Java's
Dateclass, the comparison should be of its internal state, but based only on the specific part which is persistent (the timestamp, date, or time).- Specified by:
isEqualin interfaceType- Overrides:
isEqualin classAbstractType- Parameters:
x- The first valuey- The second value- Returns:
- True if there are considered equal (see discussion above).
compare
public int compare(Object x,Object y)
Description copied from interface:TypePerform aComparator-style comparison of the given values.- Specified by:
comparein interfaceType- Overrides:
comparein classAbstractType- Parameters:
x- The first valuey- The second value- Returns:
- The comparison result.
- See Also:
Comparator.compare(Object, Object)
compare
public int compare(Object x,Object y,SessionFactoryImplementor sessionFactory)
getHashCode
public int getHashCode(Object x)
Description copied from interface:TypeGet a hash code, consistent with persistence "equality". For most types this could simply delegate to the given value'shashCode.- Specified by:
getHashCodein interfaceType- Overrides:
getHashCodein classAbstractType- Parameters:
x- The value for which to retrieve a hash code- Returns:
- The hash code
instantiate
public abstract PersistentCollection<?> instantiate(SharedSessionContractImplementor session,CollectionPersister persister,Object key)
Instantiate an uninitialized collection wrapper or holder. Callers MUST add the holder to the persistence context!- Parameters:
session- The session from which the request is originating.persister- The underlying collection persister (metadata)key- The owner key.- Returns:
- The instantiated collection.
nullSafeSet
public final void nullSafeSet(PreparedStatement st,Object value, int index, boolean[] settable,SharedSessionContractImplementor session) throwsHibernateException,SQLException
Description copied from interface:TypeBind a value represented by an instance of themapped classto the given JDBCPreparedStatement, ignoring some columns as dictated by thesettableparameter. Implementors should handle the possibility of null values. A multi-column type should bind parameters starting fromindex.- Specified by:
nullSafeSetin interfaceType- Parameters:
st- The JDBC prepared statement to which to bindvalue- the object to writeindex- starting parameter bind indexsettable- an array indicating which columns to bind/ignoresession- The originating session- Throws:
HibernateException- An error from HibernateSQLException- An error from the JDBC driver
nullSafeSet
public void nullSafeSet(PreparedStatement st,Object value, int index,SharedSessionContractImplementor session) throwsHibernateException,SQLException
Description copied from interface:TypeBind a value represented by an instance of themapped classto the given JDBCPreparedStatement, ignoring some columns as dictated by thesettableparameter. Implementors should handle the possibility of null values. A multi-column type should bind parameters starting fromindex.- Specified by:
nullSafeSetin interfaceType- Parameters:
st- The JDBC prepared statement to which to bindvalue- the object to writeindex- starting parameter bind indexsession- The originating session- Throws:
HibernateException- An error from HibernateSQLException- An error from the JDBC driver
getSqlTypeCodes
public int[] getSqlTypeCodes(Mapping session) throwsMappingException
Description copied from interface:TypeReturn the JDBC types codes as defined byTypesorSqlTypesfor the columns mapped by this type.The number of elements in this array must match the return from
Type.getColumnSpan(org.hibernate.engine.spi.Mapping).- Specified by:
getSqlTypeCodesin interfaceType- Parameters:
session- The mapping object :/- Returns:
- The JDBC type codes.
- Throws:
MappingException- Generally indicates an issue accessing the passed mapping object.
getColumnSpan
public int getColumnSpan(Mapping session) throwsMappingException
Description copied from interface:TypeHow many columns are used to persist this type?Always the same as
getSqlTypCodes(mapping).length.- Specified by:
getColumnSpanin interfaceType- Parameters:
session- The mapping object :/- Returns:
- The number of columns
- Throws:
MappingException- Generally indicates an issue accessing the passed mapping object.
toLoggableString
public String toLoggableString(Object value,SessionFactoryImplementor factory)
Description copied from interface:TypeGenerate a representation of the given value for logging purposes.- Specified by:
toLoggableStringin interfaceType- Parameters:
value- The value to be loggedfactory- The session factory- Returns:
- The loggable representation
renderLoggableString
protected String renderLoggableString(Object value,SessionFactoryImplementor factory)
deepCopy
public Object deepCopy(Object value,SessionFactoryImplementor factory)
Description copied from interface:TypeReturn a deep copy of the persistent state, stopping at entities and at collections.
getName
public String getName()
Description copied from interface:TypeReturns the abbreviated name of the type.
getElementsIterator
@Deprecatedpublic Iterator<?> getElementsIterator(Object collection,SharedSessionContractImplementor session)
Deprecated.Get an iterator over the element set of the collection, which may not yet be wrapped- Parameters:
collection- The collection to be iteratedsession- The session from which the request is originating.- Returns:
- The iterator.
getElementsIterator
public Iterator<?> getElementsIterator(Object collection)
Get an iterator over the element set of the collection, which may not yet be wrapped- Parameters:
collection- The collection to be iterated- Returns:
- The element iterator
isMutable
public boolean isMutable()
Description copied from interface:TypeAre objects of this type mutable with respect to the referencing object? Entities and collections are considered immutable because they manage their own internal state.
isInverse
@Internal@Incubatingpublic boolean isInverse(SessionFactoryImplementor factory)
disassemble
public Serializable disassemble(Object value,SharedSessionContractImplementor session,Object owner) throwsHibernateException
Description copied from interface:TypeReturn a disassembled representation of the object. This is the representation that is stored in the second-level cache.A reference to an associated entity should be disassembled to its primary key value.
- Specified by:
disassemblein interfaceType- Overrides:
disassemblein classAbstractType- Parameters:
value- the value to cachesession- the originating sessionowner- optional parent entity object (needed for collections)- Returns:
- the disassembled, deep cloned state
- Throws:
HibernateException- An error from Hibernate
disassemble
public Serializable disassemble(Object value,SessionFactoryImplementor sessionFactory) throwsHibernateException
Description copied from interface:TypeReturn a disassembled representation of the object. This is the representation that is stored in the second-level cache.A reference to an associated entity should be disassembled to its primary key value.
A high-quality implementation of this method should ensure that:
Objects.equals(disassemble(x,s), disassemble(y,s))== isEqual(x,y,sf)and that:
Objects.equals(x, assemble(disassemble(x,s),s,o))That is, the implementation must be consistent with
Type.isEqual(Object, Object, SessionFactoryImplementor)and withType.assemble(Serializable, SharedSessionContractImplementor, Object).- Specified by:
disassemblein interfaceType- Overrides:
disassemblein classAbstractType- Parameters:
value- the value to cachesessionFactory- the session factory- Returns:
- the disassembled, deep cloned state
- Throws:
HibernateException- An error from Hibernate
assemble
public Object assemble(Serializable cached,SharedSessionContractImplementor session,Object owner) throwsHibernateException
Description copied from interface:TypeReconstruct the object from its disassembled state. This function is the inverse ofType.disassemble(Object, SharedSessionContractImplementor, Object).- Specified by:
assemblein interfaceType- Overrides:
assemblein classAbstractType- Parameters:
cached- the disassembled state from the cachesession- the originating sessionowner- the parent entity object- Returns:
- the (re)assembled object
- Throws:
HibernateException- An error from Hibernate
isDirty
public boolean isDirty(Object old,Object current,SharedSessionContractImplementor session) throwsHibernateException
Description copied from interface:TypeShould the parent be considered dirty, given both the old and current value?- Specified by:
isDirtyin interfaceType- Overrides:
isDirtyin classAbstractType- Parameters:
old- the old valuecurrent- the current valuesession- The session from which the request originated.- Returns:
- true if the field is dirty
- Throws:
HibernateException- A problem occurred performing the checking
isDirty
public boolean isDirty(Object old,Object current, boolean[] checkable,SharedSessionContractImplementor session) throwsHibernateException
Description copied from interface:TypeShould the parent be considered dirty, given both the old and current value?- Specified by:
isDirtyin interfaceType- Parameters:
old- the old valuecurrent- the current valuecheckable- An array of booleans indicating which columns making up the value are actually checkablesession- The session from which the request originated.- Returns:
- true if the field is dirty
- Throws:
HibernateException- A problem occurred performing the checking
wrap
public abstract PersistentCollection<?> wrap(SharedSessionContractImplementor session,Object collection)
Wrap the naked collection instance in a wrapper, or instantiate a holder. CallersMUST add the holder to the persistence context!- Parameters:
session- The session from which the request is originating.collection- The bare collection to be wrapped.- Returns:
- The wrapped collection.
isAssociationType
public boolean isAssociationType()
Note: return true because this type is castable toAssociationType. Not because all collections are associations.- Specified by:
isAssociationTypein interfaceType- Overrides:
isAssociationTypein classAbstractType- Returns:
- True if this type is also an
AssociationTypeimplementor; false otherwise.
getForeignKeyDirection
public ForeignKeyDirection getForeignKeyDirection()
Description copied from interface:AssociationTypeGet the foreign key directionality of this association- Specified by:
getForeignKeyDirectionin interfaceAssociationType
getKeyOfOwner
public @NullableObject getKeyOfOwner(Object owner,SharedSessionContractImplementor session)
Get the key value from the owning entity instance, usually the identifier, but might be some other unique key, in the case of property-ref- Parameters:
owner- The collection ownersession- The session from which the request is originating.- Returns:
- The collection owner's key
getIdOfOwnerOrNull
public Object getIdOfOwnerOrNull(Object key,SharedSessionContractImplementor session)
Get the id value from the owning entity key, usually the same as the key, but might be some other property, in the case of property-ref- Parameters:
key- The collection owner keysession- The session from which the request is originating.- Returns:
- The collection owner's id, if it can be obtained from the key; otherwise, null is returned
isArrayType
public boolean isArrayType()
useLHSPrimaryKey
public boolean useLHSPrimaryKey()
Description copied from interface:AssociationTypeIs the primary key of the owning entity table to be used in the join?- Specified by:
useLHSPrimaryKeyin interfaceAssociationType
getRHSUniqueKeyPropertyName
public String getRHSUniqueKeyPropertyName()
Description copied from interface:AssociationTypeThe name of a unique property of the associated entity that provides the join key (null if the identifier of an entity, or key of a collection)- Specified by:
getRHSUniqueKeyPropertyNamein interfaceAssociationType
getAssociatedJoinable
public Joinable getAssociatedJoinable(SessionFactoryImplementor factory) throwsMappingException
Description copied from interface:AssociationTypeGet the "persister" for this association - a class or collection persister- Specified by:
getAssociatedJoinablein interfaceAssociationType- Throws:
MappingException
isModified
public boolean isModified(Object old,Object current, boolean[] checkable,SharedSessionContractImplementor session)
Description copied from interface:TypeHas the value been modified compared to the current database state? The difference between this and theType.isDirty(java.lang.Object, java.lang.Object, org.hibernate.engine.spi.SharedSessionContractImplementor)methods is that here we need to account for "partially" built values. This is really only an issue with association types. For most type implementations it is enough to simply delegate toType.isDirty(java.lang.Object, java.lang.Object, org.hibernate.engine.spi.SharedSessionContractImplementor).- Specified by:
isModifiedin interfaceType- Overrides:
isModifiedin classAbstractType- Parameters:
old- the database state, in a "hydrated" form, with identifiers unresolvedcurrent- the current state of the objectcheckable- which columns are actually checkablesession- The session from which the request originated.- Returns:
- true if the field has been modified
getAssociatedEntityName
public String getAssociatedEntityName(SessionFactoryImplementor factory) throwsMappingException
Description copied from interface:AssociationTypeGet the entity name of the associated entity- Specified by:
getAssociatedEntityNamein interfaceAssociationType- Throws:
MappingException
replaceElements
public Object replaceElements(Object original,Object target,Object owner,Map<Object,Object> copyCache,SharedSessionContractImplementor session)
Replace the elements of a collection with the elements of another collection.- Parameters:
original- The 'source' of the replacement elements (where we copy from)target- The target of the replacement elements (where we copy to)owner- The owner of the collection being mergedcopyCache- The map of elements already replaced.session- The session from which the merge event originated.- Returns:
- The merged collection.
instantiateResult
protected Object instantiateResult(Object original)
Instantiate a new "underlying" collection exhibiting the same capacity characteristics and the passed "original".- Parameters:
original- The original collection.- Returns:
- The newly instantiated collection.
instantiate
public abstract Object instantiate(int anticipatedSize)
Instantiate an empty instance of the "underlying" collection (not a wrapper), but with the given anticipated size (i.e. accounting for initial capacity and perhaps load factor).- Parameters:
anticipatedSize- The anticipated size of the instantiated collection after we are done populating it.- Returns:
- A newly instantiated collection to be wrapped.
replace
public Object replace(Object original,Object target,SharedSessionContractImplementor session,Object owner,Map<Object,Object> copyCache) throwsHibernateException
Description copied from interface:TypeDuring merge, replace the existing (target) value in the entity we are merging to with a new (original) value from the detached entity we are merging. For immutable objects, or null values, it is safe to simply return the first parameter. For mutable objects, it is safe to return a copy of the first parameter. For objects with component values, it might make sense to recursively replace component values.- Specified by:
replacein interfaceType- Parameters:
original- the value from the detached entity being mergedtarget- the value in the managed entitysession- The originating sessionowner- The owner of the valuecopyCache- The cache of already copied/replaced values- Returns:
- the value to be merged
- Throws:
HibernateException- An error from Hibernate
getElementType
public final Type getElementType(SessionFactoryImplementor factory) throwsMappingException
Get the Hibernate type of the collection elements- Parameters:
factory- The session factory.- Returns:
- The type of the collection elements
- Throws:
MappingException- Indicates the underlying persister could not be located.
getCollection
public Object getCollection(Object key,SharedSessionContractImplementor session,Object owner,Boolean overridingEager)
instantiate a collection wrapper (called when loading an object)- Parameters:
key- The collection owner keysession- The session from which the request is originating.owner- The collection owner- Returns:
- The collection
hasHolder
public boolean hasHolder()
initializeImmediately
protected boolean initializeImmediately()
getLHSPropertyName
public String getLHSPropertyName()
Description copied from interface:AssociationTypeGet the name of a property in the owning entity that provides the join key (null if the identifier)- Specified by:
getLHSPropertyNamein interfaceAssociationType
isAlwaysDirtyChecked
public boolean isAlwaysDirtyChecked()
We always need to dirty check the collection because we sometimes need to increment version number of owner and also because of how assemble/disassemble is implemented for uks- Specified by:
isAlwaysDirtyCheckedin interfaceAssociationType
toColumnNullness
public boolean[] toColumnNullness(Object value,Mapping mapping)
Description copied from interface:TypeGiven an instance of the type, return an array ofbooleanvalues indicating which mapped columns would be null.- Specified by:
toColumnNullnessin interfaceType- Parameters:
value- an instance of the typemapping- The mapping abstraction- Returns:
- array indicating column nullness for a value instance