PersistentCollection (Hibernate API Documentation) - Hibernate 2.1.8 正式版 API 英文文档

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.sf.hibernate.collection
Class PersistentCollection

java.lang.Object
  net.sf.hibernate.collection.PersistentCollection

All Implemented Interfaces:: Serializable

Direct Known Subclasses:: ArrayHolder, Map, ODMGCollection

public abstract class PersistentCollection
extends Object
implements Serializable

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.

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

Applications should never use classes in this package directly, unless extending the "framework" here.

Changes to 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
See Also:: Serialized Form

Constructor Summary

PersistentCollection()
          Not called by Hibernate, but used by non-JDK serialization, eg.

protected PersistentCollection(SessionImplementor session)


Method Summary

void afterRowInsert(CollectionPersister persister, Object entry, int i)
          Called after inserting a row, to fetch the natively generated id

abstract void beforeInitialize(CollectionPersister persister)
          Called before any elements are read into the collection, allowing appropriate initializations to occur.

void beginRead()
          Called just before reading any rows from the JDBC result set

void delayedAddAll(Collection coll)
          After reading all existing elements from the database, add the queued elements to the underlying collection.

abstract Serializable disassemble(CollectionPersister persister)
          Disassemble the collection, ready for the cache

abstract boolean empty()
          Is the initialized collection empty?

boolean endRead()
          Called after reading all rows from the JDBC result set

abstract Iterator entries()
          Iterate all collection entries, during update of the database

abstract boolean entryExists(Object entry, int i)
          Does an element exist at this entry in the collection?

abstract boolean equalsSnapshot(Type elementType)
          Does the current state exactly match the snapshot?

void forceInitialization()
          To be called internally by the session, forcing immediate initialization.

CollectionSnapshot getCollectionSnapshot()
          Returns the collectionSnapshot.

abstract Iterator getDeletes(Type elemType)
          Get all the elements that need deleting

abstract Object getIndex(Object entry, int i)
          Get the index of the given collection entry

protected static Collection getOrphans(Collection oldElements, Collection currentElements, SessionImplementor session)


abstract Collection getOrphans(Serializable snapshot)
          get all "orphaned" elements

protected SessionImplementor getSession()
          Get the current session

protected Serializable getSnapshot()
          Get the current snapshot from the session

Serializable getSnapshot(CollectionPersister persister)
          Return a new snapshot of the current state of the collection, or null if no persister is passed

Object getValue()
          return the user-visible collection (or array) instance

boolean hasQueuedAdditions()
          Does this instance have any "queued" additions?

protected void initialize(boolean writing)
          Initialize the collection, if possible, wrapping any exceptions in a runtime exception

abstract void initializeFromCache(CollectionPersister persister, Serializable disassembled, Object owner)
          Read the state of the collection from a disassembled cached value

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

abstract boolean isWrapper(Object collection)
          Is this the wrapper for the given underlying collection instance?

abstract boolean needsInserting(Object entry, int i, Type elemType)
          Do we need to insert this element?

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

abstract boolean needsUpdating(Object entry, int i, Type elemType)
          Do we need to update this element?

void postFlush()
          After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.

void preInsert(CollectionPersister persister)
          Called before inserting rows, to ensure that any surrogate keys are fully generated

protected boolean queueAdd(Object element)
          Queue an addition

protected boolean queueAddAll(Collection coll)
          Queue additions

Iterator queuedAdditionIterator()
          Iterate the "queued" additions

void read()
          Called by any read-only method of the collection interface

abstract Object readFrom(ResultSet rs, CollectionPersister role, Object owner)
          Read a row from the JDBC result set

void setCollectionSnapshot(CollectionSnapshot collectionSnapshot)
          Sets the collectionSnapshot.

boolean setCurrentSession(SessionImplementor session)
          Associate the collection with the given session.

protected void setDirectlyAccessible(boolean directlyAccessible)


protected void setInitialized()


protected abstract Serializable snapshot(CollectionPersister persister)
          Return a new snapshot of the current state

boolean unsetSession(SessionImplementor currentSession)
          Disassociate this collection from the given session.

boolean wasInitialized()
          Is this instance initialized?

protected void write()
          Called by any writer method of the collection interface

abstract void writeTo(PreparedStatement st, CollectionPersister role, Object entry, int i, boolean writeOrder)
          Write a row to the JDBC prepared statement

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PersistentCollection

public PersistentCollection()

Not called by Hibernate, but used by non-JDK serialization, eg. SOAP libraries.

PersistentCollection

protected PersistentCollection(SessionImplementor session)

Method Detail

empty

public abstract boolean empty()

Is the initialized collection empty?

read

public final void read()

Called by any read-only method of the collection interface

write

protected final void write()

Called by any writer method of the collection interface

queueAdd

protected final boolean queueAdd(Object element)

Queue an addition

queueAddAll

protected final boolean queueAddAll(Collection coll)

Queue additions

delayedAddAll

public void delayedAddAll(Collection coll)

After reading all existing elements from the database, add the queued elements to the underlying collection.

postFlush

public void postFlush()

After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.

getValue

public Object getValue()

return the user-visible collection (or array) instance

beginRead

public void beginRead()

Called just before reading any rows from the JDBC result set

endRead

public boolean endRead()

Called after reading all rows from the JDBC result set

initialize

protected final void initialize(boolean writing)

Initialize the collection, if possible, wrapping any exceptions in a runtime exception

Parameters:: writing - currently obsolete
Throws:: LazyInitializationException - if we cannot initialize

setInitialized

protected final void setInitialized()

setDirectlyAccessible

protected final void setDirectlyAccessible(boolean directlyAccessible)

isDirectlyAccessible

public boolean isDirectlyAccessible()

Could the application possibly have a direct reference to the underlying collection implementation?

unsetSession

public final boolean unsetSession(SessionImplementor currentSession)

Disassociate this collection from the given session.

Returns:: true if this was currently associated with the given session

setCurrentSession

public final boolean setCurrentSession(SessionImplementor session)
                                throws HibernateException

Associate the collection with the given session.

Returns:: false if the collection was already associated with the session
Throws:: HibernateException - if the collection was already associated with another open session

initializeFromCache

public abstract void initializeFromCache(CollectionPersister persister,
                                         Serializable disassembled,
                                         Object owner)
                                  throws HibernateException

Read the state of the collection from a disassembled cached value

Throws:: HibernateException

entries

public abstract Iterator entries()

Iterate all collection entries, during update of the database

readFrom

public abstract Object readFrom(ResultSet rs,
                                CollectionPersister role,
                                Object owner)
                         throws HibernateException,
                                SQLException

Read a row from the JDBC result set

Throws:: HibernateException; SQLException

writeTo

public abstract void writeTo(PreparedStatement st,
                             CollectionPersister role,
                             Object entry,
                             int i,
                             boolean writeOrder)
                      throws HibernateException,
                             SQLException

Write a row to the JDBC prepared statement

Throws:: HibernateException; SQLException

getIndex

public abstract Object getIndex(Object entry,
                                int i)

Get the index of the given collection entry

beforeInitialize

public abstract void beforeInitialize(CollectionPersister persister)

Called before any elements are read into the collection, allowing appropriate initializations to occur.

equalsSnapshot

public abstract boolean equalsSnapshot(Type elementType)
                                throws HibernateException

Does the current state exactly match the snapshot?

Throws:: HibernateException

snapshot

protected abstract Serializable snapshot(CollectionPersister persister)
                                  throws HibernateException

Return a new snapshot of the current state

Throws:: HibernateException

disassemble

public abstract Serializable disassemble(CollectionPersister persister)
                                  throws HibernateException

Disassemble the collection, ready for the cache

Throws:: HibernateException

needsRecreate

public boolean needsRecreate(CollectionPersister persister)

Do we need to completely recreate this collection when it changes?

getSnapshot

public final Serializable getSnapshot(CollectionPersister persister)
                               throws HibernateException

Return a new snapshot of the current state of the collection, or null if no persister is passed

Throws:: HibernateException

forceInitialization

public final void forceInitialization()
                               throws HibernateException

To be called internally by the session, forcing immediate initialization.

Throws:: HibernateException

entryExists

public abstract boolean entryExists(Object entry,
                                    int i)

Does an element exist at this entry in the collection?

needsInserting

public abstract boolean needsInserting(Object entry,
                                       int i,
                                       Type elemType)
                                throws HibernateException

Do we need to insert this element?

Throws:: HibernateException

needsUpdating

public abstract boolean needsUpdating(Object entry,
                                      int i,
                                      Type elemType)
                               throws HibernateException

Do we need to update this element?

Throws:: HibernateException

getDeletes

public abstract Iterator getDeletes(Type elemType)
                             throws HibernateException

Get all the elements that need deleting

Throws:: HibernateException

isWrapper

public abstract boolean isWrapper(Object collection)

Is this the wrapper for the given underlying collection instance?

getSnapshot

protected final Serializable getSnapshot()

Get the current snapshot from the session

wasInitialized

public final boolean wasInitialized()

Is this instance initialized?

hasQueuedAdditions

public final boolean hasQueuedAdditions()

Does this instance have any "queued" additions?

queuedAdditionIterator

public final Iterator queuedAdditionIterator()

Iterate the "queued" additions

getCollectionSnapshot

public CollectionSnapshot getCollectionSnapshot()

Returns the collectionSnapshot.

Returns:: CollectionSnapshot

setCollectionSnapshot

public void setCollectionSnapshot(CollectionSnapshot collectionSnapshot)

Sets the collectionSnapshot.

Parameters:: collectionSnapshot - The collectionSnapshot to set

preInsert

public void preInsert(CollectionPersister persister)
               throws HibernateException

Called before inserting rows, to ensure that any surrogate keys are fully generated

Throws:: HibernateException

afterRowInsert

public void afterRowInsert(CollectionPersister persister,
                           Object entry,
                           int i)
                    throws HibernateException

Called after inserting a row, to fetch the natively generated id

Throws:: HibernateException

getOrphans

public abstract Collection getOrphans(Serializable snapshot)
                               throws HibernateException

get all "orphaned" elements

Throws:: HibernateException

getSession

protected final SessionImplementor getSession()

Get the current session

getOrphans

protected static Collection getOrphans(Collection oldElements,
                                       Collection currentElements,
                                       SessionImplementor session)
                                throws HibernateException

Throws:: HibernateException

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Constructor Summary
	`PersistentCollection()` Not called by Hibernate, but used by non-JDK serialization, eg.
`protected`	`PersistentCollection(SessionImplementor session)`

Method Summary
`void`	`afterRowInsert(CollectionPersister persister, Object entry, int i)` Called after inserting a row, to fetch the natively generated id
`abstract void`	`beforeInitialize(CollectionPersister persister)` Called before any elements are read into the collection, allowing appropriate initializations to occur.
`void`	`beginRead()` Called just before reading any rows from the JDBC result set
`void`	`delayedAddAll(Collection coll)` After reading all existing elements from the database, add the queued elements to the underlying collection.
`abstract Serializable`	`disassemble(CollectionPersister persister)` Disassemble the collection, ready for the cache
`abstract boolean`	`empty()` Is the initialized collection empty?
`boolean`	`endRead()` Called after reading all rows from the JDBC result set
`abstract Iterator`	`entries()` Iterate all collection entries, during update of the database
`abstract boolean`	`entryExists(Object entry, int i)` Does an element exist at this entry in the collection?
`abstract boolean`	`equalsSnapshot(Type elementType)` Does the current state exactly match the snapshot?
`void`	`forceInitialization()` To be called internally by the session, forcing immediate initialization.
`CollectionSnapshot`	`getCollectionSnapshot()` Returns the collectionSnapshot.
`abstract Iterator`	`getDeletes(Type elemType)` Get all the elements that need deleting
`abstract Object`	`getIndex(Object entry, int i)` Get the index of the given collection entry
`protected static Collection`	`getOrphans(Collection oldElements, Collection currentElements, SessionImplementor session)`
`abstract Collection`	`getOrphans(Serializable snapshot)` get all "orphaned" elements
`protected SessionImplementor`	`getSession()` Get the current session
`protected Serializable`	`getSnapshot()` Get the current snapshot from the session
`Serializable`	`getSnapshot(CollectionPersister persister)` Return a new snapshot of the current state of the collection, or null if no persister is passed
`Object`	`getValue()` return the user-visible collection (or array) instance
`boolean`	`hasQueuedAdditions()` Does this instance have any "queued" additions?
`protected void`	`initialize(boolean writing)` Initialize the collection, if possible, wrapping any exceptions in a runtime exception
`abstract void`	`initializeFromCache(CollectionPersister persister, Serializable disassembled, Object owner)` Read the state of the collection from a disassembled cached value
`boolean`	`isDirectlyAccessible()` Could the application possibly have a direct reference to the underlying collection implementation?
`abstract boolean`	`isWrapper(Object collection)` Is this the wrapper for the given underlying collection instance?
`abstract boolean`	`needsInserting(Object entry, int i, Type elemType)` Do we need to insert this element?
`boolean`	`needsRecreate(CollectionPersister persister)` Do we need to completely recreate this collection when it changes?
`abstract boolean`	`needsUpdating(Object entry, int i, Type elemType)` Do we need to update this element?
`void`	`postFlush()` After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.
`void`	`preInsert(CollectionPersister persister)` Called before inserting rows, to ensure that any surrogate keys are fully generated
`protected boolean`	`queueAdd(Object element)` Queue an addition
`protected boolean`	`queueAddAll(Collection coll)` Queue additions
`Iterator`	`queuedAdditionIterator()` Iterate the "queued" additions
`void`	`read()` Called by any read-only method of the collection interface
`abstract Object`	`readFrom(ResultSet rs, CollectionPersister role, Object owner)` Read a row from the JDBC result set
`void`	`setCollectionSnapshot(CollectionSnapshot collectionSnapshot)` Sets the collectionSnapshot.
`boolean`	`setCurrentSession(SessionImplementor session)` Associate the collection with the given session.
`protected void`	`setDirectlyAccessible(boolean directlyAccessible)`
`protected void`	`setInitialized()`
`protected abstract Serializable`	`snapshot(CollectionPersister persister)` Return a new snapshot of the current state
`boolean`	`unsetSession(SessionImplementor currentSession)` Disassociate this collection from the given session.
`boolean`	`wasInitialized()` Is this instance initialized?
`protected void`	`write()` Called by any writer method of the collection interface
`abstract void`	`writeTo(PreparedStatement st, CollectionPersister role, Object entry, int i, boolean writeOrder)` Write a row to the JDBC prepared statement

PersistentCollection (Hibernate API Documentation) - Hibernate 2.1.8 正式版 API 英文文档

net.sf.hibernate.collection Class PersistentCollection

PersistentCollection

PersistentCollection

empty

read

write

queueAdd

queueAddAll

delayedAddAll

postFlush

getValue

beginRead

endRead

initialize

setInitialized

setDirectlyAccessible

isDirectlyAccessible

unsetSession

setCurrentSession

initializeFromCache

entries

readFrom

writeTo

getIndex

beforeInitialize

equalsSnapshot

snapshot

disassemble

needsRecreate

getSnapshot

forceInitialization

entryExists

needsInserting

needsUpdating

getDeletes

isWrapper

getSnapshot

wasInitialized

hasQueuedAdditions

queuedAdditionIterator

getCollectionSnapshot

setCollectionSnapshot

preInsert

afterRowInsert

getOrphans

getSession

getOrphans

net.sf.hibernate.collection
Class PersistentCollection