org.hibernate.persister.collection.CollectionPersister Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of hibernate-core Show documentation
Hibernate's core ORM functionality
There is a newer version: 7.0.0.Alpha1
/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or .
 */
package org.hibernate.persister.collection;

import java.io.Serializable;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Map;

import org.hibernate.HibernateException;
import org.hibernate.MappingException;
import org.hibernate.cache.spi.access.CollectionDataAccess;
import org.hibernate.cache.spi.entry.CacheEntryStructure;
import org.hibernate.collection.spi.PersistentCollection;
import org.hibernate.engine.spi.SessionFactoryImplementor;
import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.id.IdentifierGenerator;
import org.hibernate.metadata.CollectionMetadata;
import org.hibernate.metamodel.model.domain.NavigableRole;
import org.hibernate.persister.entity.EntityPersister;
import org.hibernate.persister.walking.spi.CollectionDefinition;
import org.hibernate.type.CollectionType;
import org.hibernate.type.Type;

/**
 * A strategy for persisting a collection role. Defines a contract between
 * the persistence strategy and the actual persistent collection framework
 * and session. Does not define operations that are required for querying
 * collections, or loading by outer join.

 * 

 * Implements persistence of a collection instance while the instance is
 * referenced in a particular role.

 * 

 * This class is highly coupled to the PersistentCollection
 * hierarchy, since double dispatch is used to load and update collection
 * elements.

 * 

 * May be considered an immutable view of the mapping object
 * 
 * Unless a customer {@link org.hibernate.persister.spi.PersisterFactory} is used, it is expected
 * that implementations of CollectionDefinition define a constructor accepting the following arguments:

 *     
 *         {@link org.hibernate.mapping.Collection} - The metadata about the collection to be handled
 *         by the persister
 *     
 *     
 *         {@link CollectionDataAccess} - the second level caching strategy for this collection
 *     
 *     
 *         {@link org.hibernate.persister.spi.PersisterCreationContext} - access to additional
 *         information useful while constructing the persister.
 *     
 * 
 *
 * @see QueryableCollection
 * @see org.hibernate.collection.spi.PersistentCollection
 * @author Gavin King
 */
public interface CollectionPersister extends CollectionDefinition {
	/**
	 * Initialize the given collection with the given key
	 * TODO: add owner argument!!
	 */
	void initialize(Serializable key, SharedSessionContractImplementor session) throws HibernateException;
	/**
	 * Is this collection role cacheable
	 */
	boolean hasCache();
	/**
	 * Get the cache
	 */
	CollectionDataAccess getCacheAccessStrategy();

	NavigableRole getNavigableRole();

	/**
	 * Get the cache structure
	 */
	CacheEntryStructure getCacheEntryStructure();
	/**
	 * Get the associated Type
	 */
	CollectionType getCollectionType();
	/**
	 * Get the "key" type (the type of the foreign key)
	 */
	Type getKeyType();
	/**
	 * Get the "index" type for a list or map (optional operation)
	 */
	Type getIndexType();
	/**
	 * Get the "element" type
	 */
	Type getElementType();
	/**
	 * Return the element class of an array, or null otherwise
	 */
	Class getElementClass();
	/**
	 * Read the key from a row of the JDBC ResultSet
	 */
	Object readKey(ResultSet rs, String[] keyAliases, SharedSessionContractImplementor session)
		throws HibernateException, SQLException;
	/**
	 * Read the element from a row of the JDBC ResultSet
	 */
	Object readElement(
			ResultSet rs,
			Object owner,
			String[] columnAliases,
			SharedSessionContractImplementor session)
		throws HibernateException, SQLException;
	/**
	 * Read the index from a row of the JDBC ResultSet
	 */
	Object readIndex(ResultSet rs, String[] columnAliases, SharedSessionContractImplementor session)
		throws HibernateException, SQLException;
	/**
	 * Read the identifier from a row of the JDBC ResultSet
	 */
	Object readIdentifier(
			ResultSet rs,
			String columnAlias,
			SharedSessionContractImplementor session)
		throws HibernateException, SQLException;
	/**
	 * Is this an array or primitive values?
	 */
	boolean isPrimitiveArray();
	/**
	 * Is this an array?
	 */
	boolean isArray();
	/**
	 * Is this a one-to-many association?
	 */
	boolean isOneToMany();
	/**
	 * Is this a many-to-many association?  Note that this is mainly
	 * a convenience feature as the single persister does not
	 * conatin all the information needed to handle a many-to-many
	 * itself, as internally it is looked at as two many-to-ones.
	 */
	boolean isManyToMany();

	String getManyToManyFilterFragment(String alias, Map enabledFilters);

	/**
	 * Is this an "indexed" collection? (list or map)
	 */
	boolean hasIndex();
	/**
	 * Is this collection lazyily initialized?
	 */
	boolean isLazy();
	/**
	 * Is this collection "inverse", so state changes are not
	 * propogated to the database.
	 */
	boolean isInverse();
	/**
	 * Completely remove the persistent state of the collection
	 */
	void remove(Serializable id, SharedSessionContractImplementor session)
		throws HibernateException;
	/**
	 * (Re)create the collection's persistent state
	 */
	void recreate(
			PersistentCollection collection,
			Serializable key,
			SharedSessionContractImplementor session)
		throws HibernateException;
	/**
	 * Delete the persistent state of any elements that were removed from
	 * the collection
	 */
	void deleteRows(
			PersistentCollection collection,
			Serializable key,
			SharedSessionContractImplementor session)
		throws HibernateException;
	/**
	 * Update the persistent state of any elements that were modified
	 */
	void updateRows(
			PersistentCollection collection,
			Serializable key,
			SharedSessionContractImplementor session)
		throws HibernateException;
	/**
	 * Insert the persistent state of any new collection elements
	 */
	void insertRows(
			PersistentCollection collection,
			Serializable key,
			SharedSessionContractImplementor session)
		throws HibernateException;
	
	/**
	 * Process queued operations within the PersistentCollection.
	 */
	void processQueuedOps(
			PersistentCollection collection,
			Serializable key,
			SharedSessionContractImplementor session)
			throws HibernateException;
	
	/**
	 * Get the name of this collection role (the fully qualified class name,
	 * extended by a "property path")
	 */
	String getRole();
	/**
	 * Get the persister of the entity that "owns" this collection
	 */
	EntityPersister getOwnerEntityPersister();
	/**
	 * Get the surrogate key generation strategy (optional operation)
	 */
	IdentifierGenerator getIdentifierGenerator();
	/**
	 * Get the type of the surrogate key
	 */
	Type getIdentifierType();
	/**
	 * Does this collection implement "orphan delete"?
	 */
	boolean hasOrphanDelete();
	/**
	 * Is this an ordered collection? (An ordered collection is
	 * ordered by the initialization operation, not by sorting
	 * that happens in memory, as in the case of a sorted collection.)
	 */
	boolean hasOrdering();

	boolean hasManyToManyOrdering();

	/**
	 * Get the "space" that holds the persistent state
	 */
	Serializable[] getCollectionSpaces();

	CollectionMetadata getCollectionMetadata();

	/**
	 * Is cascade delete handled by the database-level
	 * foreign key constraint definition?
	 */
	boolean isCascadeDeleteEnabled();
	
	/**
	 * Does this collection cause version increment of the 
	 * owning entity?
	 */
	boolean isVersioned();
	
	/**
	 * Can the elements of this collection change?
	 */
	boolean isMutable();
	
	//public boolean isSubselectLoadable();
	
	void postInstantiate() throws MappingException;
	
	SessionFactoryImplementor getFactory();

	boolean isAffectedByEnabledFilters(SharedSessionContractImplementor session);

	/**
	 * Generates the collection's key column aliases, based on the given
	 * suffix.
	 *
	 * @param suffix The suffix to use in the key column alias generation.
	 * @return The key column aliases.
	 */
	String[] getKeyColumnAliases(String suffix);

	/**
	 * Generates the collection's index column aliases, based on the given
	 * suffix.
	 *
	 * @param suffix The suffix to use in the index column alias generation.
	 * @return The key column aliases, or null if not indexed.
	 */
	String[] getIndexColumnAliases(String suffix);

	/**
	 * Generates the collection's element column aliases, based on the given
	 * suffix.
	 *
	 * @param suffix The suffix to use in the element column alias generation.
	 * @return The key column aliases.
	 */
	String[] getElementColumnAliases(String suffix);

	/**
	 * Generates the collection's identifier column aliases, based on the given
	 * suffix.
	 *
	 * @param suffix The suffix to use in the key column alias generation.
	 * @return The key column aliases.
	 */
	String getIdentifierColumnAlias(String suffix);
	
	boolean isExtraLazy();
	int getSize(Serializable key, SharedSessionContractImplementor session);
	boolean indexExists(Serializable key, Object index, SharedSessionContractImplementor session);
	boolean elementExists(Serializable key, Object element, SharedSessionContractImplementor session);
	Object getElementByIndex(Serializable key, Object index, SharedSessionContractImplementor session, Object owner);
	int getBatchSize();

	/**
	 * @return the name of the property this collection is mapped by
	 */
	String getMappedByProperty();
}