NHibernate : NHibernate.Collection Namespace

IPersistentCollection Interface

Persistent collections are treated as value objects by NHibernate. 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.

NHibernate "wraps" a collection in an instance of NHibernate.Collection.IPersistentCollection. 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 namespace 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.

public interface IPersistentCollection

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

Members

Public Properties

CollectionSnapshot NHibernate.Engine.ICollectionSnapshot .
[read-only]
Empty bool . Is the initialized collection empty?
[read-only]
HasQueuedAdds bool .
IsDirectlyAccessible bool . Gets a bool indicating if the underlying collection is directly accessable through code.
[read-only]
IsDirty bool . Is the collection dirty? Note that this is only reliable during the flush cycle, after the collection elements are dirty checked against the snapshot.
Owner object . The owning entity.
[read-only]
QueuedAddsCollection ICollection .
[read-only]
WasInitialized bool .

Public Methods

AfterInitialize (NHibernate.Persister.Collection.ICollectionPersister) : bool
Called after initializing from cache
AfterRowInsert (NHibernate.Persister.Collection.ICollectionPersister, object, int)
Called after inserting a row, to fetch the natively generated id
BeforeInitialize (NHibernate.Persister.Collection.ICollectionPersister)
Called before any elements are read into the collection, allowing appropriate initializations to occur.
BeginRead ()
Called just before reading any rows from the System.Data.IDataReader
ClearDirty ()
Clear the dirty flag, after flushing changes to the database.
Dirty ()
Mark the collection as dirty
Disassemble (NHibernate.Persister.Collection.ICollectionPersister) : object
Disassemble the collection, ready for the cache
EndRead (NHibernate.Persister.Collection.ICollectionPersister) : bool
Called after reading all rows from the System.Data.IDataReader
Entries () : IEnumerable
Iterate all collection entries, during update of the database
EntryExists (object, int) : bool
Does an element exist at this entry in the collection?
EqualsSnapshot (NHibernate.Type.IType) : bool
Does the current state exactly match the snapshot?
ForceInitialization ()
To be called internally by the session, forcing immediate initalization.
GetDeletes (NHibernate.Type.IType, bool) : ICollection
Get all the elements that need deleting
GetElement (object) : object
Get the value of the given collection entry
GetIdentifier (object, int) : object
Get the identifier of the given collection entry
GetIndex (object, int) : object
Get the index of the given collection entry
GetOrphans (object, Type) : ICollection
Get all "orphaned" elements
GetSnapshot (NHibernate.Persister.Collection.ICollectionPersister) : ICollection
Return a new snapshot of the current state of the collection
GetSnapshotElement (object, int) : object
Get the snapshot value of the given collection entry
GetValue () : object
Return the user-visible collection (or array) instance
InitializeFromCache (NHibernate.Persister.Collection.ICollectionPersister, object, object)
Read the state of the collection from a disassembled cached value.
IsSnapshotEmpty (ICollection) : bool
Documentation for this section has not yet been entered.
IsWrapper (object) : bool
Is this the wrapper for the given underlying collection instance?
NeedsInserting (object, int, NHibernate.Type.IType) : bool
Do we need to insert this element?
NeedsRecreate (NHibernate.Persister.Collection.ICollectionPersister) : bool
Gets a bool indicating if the rows for this collection need to be recreated in the table.
NeedsUpdating (object, int, NHibernate.Type.IType) : bool
Do we need to update this element?
PostAction ()
Clears out any Queued Additions.
PreInsert (NHibernate.Persister.Collection.ICollectionPersister)
Called before inserting rows, to ensure that any surrogate keys are fully generated
ReadFrom (System.Data.IDataReader, NHibernate.Persister.Collection.ICollectionPersister, NHibernate.Loader.ICollectionAliases, object) : object
Reads the row from the System.Data.IDataReader.
SetCurrentSession (NHibernate.Engine.ISessionImplementor) : bool
Associate the collection with the given session.
UnsetSession (NHibernate.Engine.ISessionImplementor) : bool
Disassociate this collection from the given session.

Member Details

AfterInitialize Method

Called after initializing from cache

Parameters

persister
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

AfterRowInsert Method

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

public void AfterRowInsert (NHibernate.Persister.Collection.ICollectionPersister persister, object entry, int i)

Parameters

persister
entry
i

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

BeforeInitialize Method

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

Parameters

persister
The NHibernate.Persister.Collection.ICollectionPersister for this persistent collection.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

BeginRead Method

Called just before reading any rows from the System.Data.IDataReader

public void BeginRead ()

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

ClearDirty Method

Clear the dirty flag, after flushing changes to the database.

public void ClearDirty ()

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

CollectionSnapshot Property

public NHibernate.Engine.ICollectionSnapshot CollectionSnapshot { set; get; }

Value

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

Dirty Method

Mark the collection as dirty

public void Dirty ()

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

Disassemble Method

Disassemble the collection, ready for the cache

Parameters

persister
The NHibernate.Persister.Collection.ICollectionPersister for this Collection.

Returns

The contents of the persistent collection in a cacheable form.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

Empty Property

Is the initialized collection empty?

public bool Empty { get; }

Value

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

EndRead Method

Called after reading all rows from the System.Data.IDataReader

Parameters

persister
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

This should be overridden by sub collections that use temporary collections to store values read from the db.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

Entries Method

Iterate all collection entries, during update of the database

public IEnumerable Entries ()

Returns

An IEnumerable that gives access to all entries in the collection.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

EntryExists Method

Does an element exist at this entry in the collection?

public bool EntryExists (object entry, int i)

Parameters

entry
Documentation for this section has not yet been entered.
i
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

EqualsSnapshot Method

Does the current state exactly match the snapshot?

public bool EqualsSnapshot (NHibernate.Type.IType elementType)

Parameters

elementType
The NHibernate.Type.IType to compare the elements of the Collection.

Returns

true if the wrapped collection is different than the snapshot of the collection or if one of the elements in the collection is dirty.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

ForceInitialization Method

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

public void ForceInitialization ()

Remarks

This method is similar to AbstractPersistentCollection.Initialize(bool), except that different exceptions are thrown.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetDeletes Method

Get all the elements that need deleting

public ICollection GetDeletes (NHibernate.Type.IType elemType, bool indexIsFormula)

Parameters

elemType
Documentation for this section has not yet been entered.
indexIsFormula
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetElement Method

Get the value of the given collection entry

public object GetElement (object entry)

Parameters

entry
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetIdentifier Method

Get the identifier of the given collection entry

public object GetIdentifier (object entry, int i)

Parameters

entry
Documentation for this section has not yet been entered.
i
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetIndex Method

Get the index of the given collection entry

public object GetIndex (object entry, int i)

Parameters

entry
Documentation for this section has not yet been entered.
i
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetOrphans Method

Get all "orphaned" elements

public ICollection GetOrphans (object snapshot, Type entityName)

Parameters

snapshot
The snapshot of the collection.
entityName
The persistent class whose objects the collection is expected to contain.

Returns

An ICollection that contains all of the elements that have been orphaned.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetSnapshot Method

Return a new snapshot of the current state of the collection

Parameters

persister
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetSnapshotElement Method

Get the snapshot value of the given collection entry

public object GetSnapshotElement (object entry, int i)

Parameters

entry
Documentation for this section has not yet been entered.
i
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

GetValue Method

Return the user-visible collection (or array) instance

public object GetValue ()

Returns

By default, the NHibernate wrapper is an acceptable collection for the end user code to work with because it is interface compatible. An NHibernate PersistentList is an IList, an NHibernate PersistentMap is an IDictionary and those are the types user code is expecting.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

HasQueuedAdds Property

public bool HasQueuedAdds { get; }

Value

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

InitializeFromCache Method

Read the state of the collection from a disassembled cached value.

public void InitializeFromCache (NHibernate.Persister.Collection.ICollectionPersister persister, object disassembled, object owner)

Parameters

persister
disassembled
owner

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

IsDirectlyAccessible Property

Gets a bool indicating if the underlying collection is directly accessable through code.

public bool IsDirectlyAccessible { set; get; }

Value

true if we are not guaranteed that the NHibernate collection wrapper is being used.

Remarks

This is typically false whenever a transient object that contains a collection is being associated with an NHibernate.ISession through NHibernate.ISession.Save(object) or NHibernate.ISession.SaveOrUpdate(object). NHibernate can't guarantee that it will know about all operations that would cause NHibernate's collections to call AbstractPersistentCollection.Read or AbstractPersistentCollection.Write.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

IsDirty Property

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 bool IsDirty { get; }

Value

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

IsSnapshotEmpty Method

Documentation for this section has not yet been entered.

public bool IsSnapshotEmpty (ICollection snapshot)

Parameters

snapshot
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

IsWrapper Method

Is this the wrapper for the given underlying collection instance?

public bool IsWrapper (object collection)

Parameters

collection
The collection to see if this IPersistentCollection is wrapping.

Returns

true if the IPersistentCollection is wrappping the collection instance, false otherwise.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

NeedsInserting Method

Do we need to insert this element?

public bool NeedsInserting (object entry, int i, NHibernate.Type.IType elemType)

Parameters

entry
Documentation for this section has not yet been entered.
i
Documentation for this section has not yet been entered.
elemType
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

NeedsRecreate Method

Gets a bool indicating if the rows for this collection need to be recreated in the table.

Parameters

persister
The NHibernate.Persister.Collection.ICollectionPersister for this Collection.

Returns

false by default since most collections can determine which rows need to be individually updated/inserted/deleted. Currently only NHibernate.Collection.PersistentBag's for many-to-many need to be recreated.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

NeedsUpdating Method

Do we need to update this element?

public bool NeedsUpdating (object entry, int i, NHibernate.Type.IType elemType)

Parameters

entry
Documentation for this section has not yet been entered.
i
Documentation for this section has not yet been entered.
elemType
Documentation for this section has not yet been entered.

Returns

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

Owner Property

The owning entity.

public object Owner { set; get; }

Value

Documentation for this section has not yet been entered.

Remarks

Note that the owner is only set during the flush cycle, and when a new collection wrapper is created while loading an entity.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

PostAction Method

Clears out any Queued Additions.

public void PostAction ()

Remarks

After a Flush() the database is in synch with the in-memory contents of the Collection. Since everything is in synch remove any Queued Additions.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

PreInsert Method

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

Parameters

persister

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

QueuedAddsCollection Property

public ICollection QueuedAddsCollection { get; }

Value

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

ReadFrom Method

Reads the row from the System.Data.IDataReader.

Parameters

reader
The IDataReader that contains the value of the Identifier
role
The persister for this Collection.
descriptor
The descriptor providing result set column names
owner
The owner of this Collection.

Returns

The object that was contained in the row.

Remarks

This method should be prepared to handle duplicate elements caused by fetching multiple collections, or NHibernate.Hql.Classic.QueryTranslator.FetchedCollections.IsUnsafe(NHibernate.Persister.Collection.IQueryableCollection) should be updated to return true for the collection type.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

SetCurrentSession Method

Associate the collection with the given session.

public bool SetCurrentSession (NHibernate.Engine.ISessionImplementor session)

Parameters

session

Returns

false if the collection was already associated with the session

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

UnsetSession Method

Disassociate this collection from the given session.

public bool UnsetSession (NHibernate.Engine.ISessionImplementor session)

Parameters

session

Returns

true if this was currently associated with the given session

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000

WasInitialized Property

public bool WasInitialized { get; }

Value

Documentation for this section has not yet been entered.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: NHibernate.Collection
Assembly: NHibernate (in NHibernate.dll)
Assembly Versions: 1.2.1.4000