Hibernate example source code file (PersistentCollection.java)

This example Hibernate source code file (PersistentCollection.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Hibernate tags/keywords

collection, collectionaliases, collectionpersister, hibernateexception, hibernateexception, io, iterator, jdbc, object, object, serializable, serializable, sql, sqlexception, string, string, type, util

The Hibernate PersistentCollection.java source code

/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2008-2011, Red Hat Inc. or third-party contributors as
 * indicated by the @author tags or express copyright attribution
 * statements applied by the authors.  All third-party contributions are
 * distributed under license by Red Hat Inc.
 *
 * This copyrighted material is made available to anyone wishing to use, modify,
 * copy, or redistribute it subject to the terms and conditions of the GNU
 * Lesser General Public License, as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this distribution; if not, write to:
 * Free Software Foundation, Inc.
 * 51 Franklin Street, Fifth Floor
 * Boston, MA  02110-1301  USA
 */
package org.hibernate.collection.spi;

import java.io.Serializable;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Collection;
import java.util.Iterator;

import org.hibernate.HibernateException;
import org.hibernate.engine.spi.SessionImplementor;
import org.hibernate.loader.CollectionAliases;
import org.hibernate.persister.collection.CollectionPersister;
import org.hibernate.type.Type;

/**
 * Persistent collections are treated as value objects by Hibernate.
 * ie. they have no independent existence beyond the object holding
 * a reference to them. Unlike instances of entity classes, they are
 * automatically deleted when unreferenced and automatically become
 * persistent when held by a persistent object. Collections can be
 * passed between different objects (change "roles") and this might
 * cause their elements to move from one database table to another.<br>
 * <br>
 * Hibernate "wraps" a java collection in an instance of
 * PersistentCollection. This mechanism is designed to support
 * tracking of changes to the collection's persistent state and
 * lazy instantiation of collection elements. The downside is that
 * only certain abstract collection types are supported and any
 * extra semantics are lost<br>
 * <br>
 * Applications should <em>never use classes in this package
 * directly, unless extending the "framework" here.<br>
 * <br>
 * Changes to <em>structure of the collection are recorded by the
 * collection calling back to the session. Changes to mutable
 * elements (ie. composite elements) are discovered by cloning their
 * state when the collection is initialized and comparing at flush
 * time.
 *
 * @author Gavin King
 */
public interface PersistentCollection {
	
	/**
	 * Get the owning entity. Note that the owner is only
	 * set during the flush cycle, and when a new collection
	 * wrapper is created while loading an entity.
	 */
	public Object getOwner();
	/**
	 * Set the reference to the owning entity
	 */
	public void setOwner(Object entity);
	
	/**
	 * Is the collection empty? (don't try to initialize the collection)
	 */
	public boolean empty();

	/**
	 * After flushing, re-init snapshot state.
	 */
	public void setSnapshot(Serializable key, String role, Serializable snapshot);
	
	/**
	 * After flushing, clear any "queued" additions, since the
	 * database state is now synchronized with the memory state.
	 */
	public void postAction();
	
	/**
	 * return the user-visible collection (or array) instance
	 */
	public Object getValue();

	/**
	 * Called just before reading any rows from the JDBC result set
	 */
	public void beginRead();

	/**
	 * Called after reading all rows from the JDBC result set
	 */
	public boolean endRead();
	
	/**
	 * Called after initializing from cache
	 */
	public boolean afterInitialize();

	/**
	 * Could the application possibly have a direct reference to
	 * the underlying collection implementation?
	 */
	public boolean isDirectlyAccessible();

	/**
	 * Disassociate this collection from the given session.
	 * @return true if this was currently associated with the given session
	 */
	public boolean unsetSession(SessionImplementor currentSession);

	/**
	 * Associate the collection with the given session.
	 * @return false if the collection was already associated with the session
	 * @throws HibernateException if the collection was already associated
	 * with another open session
	 */
	public boolean setCurrentSession(SessionImplementor session)
			throws HibernateException;

	/**
	 * Read the state of the collection from a disassembled cached value
	 */
	public void initializeFromCache(CollectionPersister persister,
			Serializable disassembled, Object owner) throws HibernateException;

	/**
	 * Iterate all collection entries, during update of the database
	 */
	public Iterator entries(CollectionPersister persister);

	/**
	 * Read a row from the JDBC result set
	 */
	public Object readFrom(ResultSet rs, CollectionPersister role, CollectionAliases descriptor, Object owner)
			throws HibernateException, SQLException;

	/**
	 * Get the index of the given collection entry
	 */
	public Object getIdentifier(Object entry, int i);
	
	/**
	 * Get the index of the given collection entry
	 * @param persister it was more elegant before we added this...
	 */
	public Object getIndex(Object entry, int i, CollectionPersister persister);
	
	/**
	 * Get the value of the given collection entry
	 */
	public Object getElement(Object entry);
	
	/**
	 * Get the snapshot value of the given collection entry
	 */
	public Object getSnapshotElement(Object entry, int i);

	/**
	 * Called before any elements are read into the collection,
	 * allowing appropriate initializations to occur.
	 *
	 * @param persister The underlying collection persister.
	 * @param anticipatedSize The anticipated size of the collection after initilization is complete.
	 */
	public void beforeInitialize(CollectionPersister persister, int anticipatedSize);

	/**
	 * Does the current state exactly match the snapshot?
	 */
	public boolean equalsSnapshot(CollectionPersister persister) 
		throws HibernateException;

	/**
	 * Is the snapshot empty?
	 */
	public boolean isSnapshotEmpty(Serializable snapshot);
	
	/**
	 * Disassemble the collection, ready for the cache
	 */
	public Serializable disassemble(CollectionPersister persister)
	throws HibernateException;

	/**
	 * Do we need to completely recreate this collection when it changes?
	 */
	public boolean needsRecreate(CollectionPersister persister);

	/**
	 * Return a new snapshot of the current state of the collection
	 */
	public Serializable getSnapshot(CollectionPersister persister)
			throws HibernateException;

	/**
	 * To be called internally by the session, forcing
	 * immediate initialization.
	 */
	public void forceInitialization() throws HibernateException;

	/**
	 * Does an element exist at this entry in the collection?
	 */
	public boolean entryExists(Object entry, int i); //note that i parameter is now unused (delete it?)

	/**
	 * Do we need to insert this element?
	 */
	public boolean needsInserting(Object entry, int i, Type elemType)
			throws HibernateException;

	/**
	 * Do we need to update this element?
	 */
	public boolean needsUpdating(Object entry, int i, Type elemType)
			throws HibernateException;
	
	public boolean isRowUpdatePossible();

	/**
	 * Get all the elements that need deleting
	 */
	public Iterator getDeletes(CollectionPersister persister, boolean indexIsFormula) 
			throws HibernateException;

	/**
	 * Is this the wrapper for the given underlying collection instance?
	 */
	public boolean isWrapper(Object collection);

	/**
	 * Is this instance initialized?
	 */
	public boolean wasInitialized();

	/**
	 * Does this instance have any "queued" additions?
	 */
	public boolean hasQueuedOperations();

	/**
	 * Iterate the "queued" additions
	 */
	public Iterator queuedAdditionIterator();
	
	/**
	 * Get the "queued" orphans
	 */
	public Collection getQueuedOrphans(String entityName);
	
	/**
	 * Get the current collection key value
	 */
	public Serializable getKey();
	
	/**
	 * Get the current role name
	 */
	public String getRole();
	
	/**
	 * Is the collection unreferenced?
	 */
	public boolean isUnreferenced();
	
	/**
	 * Is the collection dirty? Note that this is only
	 * reliable during the flush cycle, after the 
	 * collection elements are dirty checked against
	 * the snapshot.
	 */
	public boolean isDirty();
	
	/**
	 * Clear the dirty flag, after flushing changes
	 * to the database.
	 */
	public void clearDirty();
	
	/**
	 * Get the snapshot cached by the collection
	 * instance
	 */
	public Serializable getStoredSnapshot();
	
	/**
	 * Mark the collection as dirty
	 */
	public void dirty();
	
	/**
	 * Called before inserting rows, to ensure that any surrogate keys
	 * are fully generated
	 */
	public void preInsert(CollectionPersister persister)
	throws HibernateException;

	/**
	 * Called after inserting a row, to fetch the natively generated id
	 */
	public void afterRowInsert(CollectionPersister persister, Object entry, int i) 
	throws HibernateException;

	/**
	 * get all "orphaned" elements
	 */
	public Collection getOrphans(Serializable snapshot, String entityName)
	throws HibernateException;
	
}