From: Michael D. <mik...@us...> - 2004-11-29 04:46:04
|
Update of /cvsroot/nhibernate/nhibernate/src/NHibernate/Impl In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31197/src/NHibernate/Impl Modified Files: ScheduledInsertion.cs SessionImpl.cs Log Message: Added some comments about how the CollectionEntry is working and some more comments to individual collection classes. Index: SessionImpl.cs =================================================================== RCS file: /cvsroot/nhibernate/nhibernate/src/NHibernate/Impl/SessionImpl.cs,v retrieving revision 1.49 retrieving revision 1.50 diff -C2 -d -r1.49 -r1.50 *** SessionImpl.cs 28 Nov 2004 21:47:46 -0000 1.49 --- SessionImpl.cs 29 Nov 2004 04:45:51 -0000 1.50 *************** *** 134,137 **** --- 134,147 ---- private string _className; + /// <summary> + /// Initializes a new instance of EntityEntry. + /// </summary> + /// <param name="status">The current <see cref="Status"/> of the Entity.</param> + /// <param name="loadedState">The snapshot of the Entity's state when it was loaded.</param> + /// <param name="id">The identifier of the Entity in the database.</param> + /// <param name="version">The version of the Entity.</param> + /// <param name="lockMode">The <see cref="LockMode"/> for the Entity.</param> + /// <param name="existsInDatabase">A boolean indicating if the Entity exists in the database.</param> + /// <param name="persister">The <see cref="IClassPersister"/> that is responsible for this Entity.</param> public EntityEntry(Status status, object[] loadedState, object id, object version, LockMode lockMode, bool existsInDatabase, IClassPersister persister) { *************** *** 146,150 **** } ! public LockMode LockMode { --- 156,163 ---- } ! /// <summary> ! /// Gets or sets the current <see cref="LockMode"/> of the Entity. ! /// </summary> ! /// <value>The <see cref="LockMode"/> of the Entity.</value> public LockMode LockMode { *************** *** 153,156 **** --- 166,174 ---- } + /// <summary> + /// Gets or sets the <see cref="Status"/> of this Entity with respect to its + /// persistence in the database. + /// </summary> + /// <value>The <see cref="Status"/> of this Entity.</value> public Status Status { *************** *** 159,162 **** --- 177,186 ---- } + /// <summary> + /// Gets or sets the identifier of the Entity in the database. + /// </summary> + /// <value>The identifier of the Entity in the database if one has been assigned.</value> + /// <remarks>This might be <c>null</c> when the <see cref="EntityEntry.Status"/> is + /// <see cref="Status.Saving"/> and the database generates the id.</remarks> public object Id { *************** *** 165,168 **** --- 189,199 ---- } + /// <summary> + /// Gets or sets the snapshot of the Entity when it was loaded from the database. + /// </summary> + /// <value>The snapshot of the Entity.</value> + /// <remarks> + /// There will only be a value when the Entity was loaded in the current Session. + /// </remarks> public object[] LoadedState { *************** *** 171,174 **** --- 202,210 ---- } + /// <summary> + /// Gets or sets the snapshot of the Entity when it was marked as being ready for deletion. + /// </summary> + /// <value>The snapshot of the Entity.</value> + /// <remarks>This will be <c>null</c> if the Entity is not being deleted.</remarks> public object[] DeletedState { *************** *** 177,180 **** --- 213,224 ---- } + /// <summary> + /// Gets or sets a <see cref="Boolean"/> indicating if this Entity exists in the database. + /// </summary> + /// <value><c>true</c> if it is already in the database.</value> + /// <remarks> + /// It can also be <c>true</c> if it does not exists in the database yet and the + /// <see cref="IClassPersister.IsIdentifierAssignedByInsert"/> is <c>true</c>. + /// </remarks> public bool ExistsInDatabase { *************** *** 183,186 **** --- 227,234 ---- } + /// <summary> + /// Gets or sets the version of the Entity. + /// </summary> + /// <value>The version of the Entity.</value> public object Version { *************** *** 189,192 **** --- 237,244 ---- } + /// <summary> + /// Gets or sets the <see cref="IClassPersister"/> that is responsible for this Entity. + /// </summary> + /// <value>The <see cref="IClassPersister"/> that is reponsible for this Entity.</value> public IClassPersister Persister { *************** *** 195,202 **** } public string ClassName { get { return _className; } - set { _className = value; } } --- 247,257 ---- } + /// <summary> + /// Gets the Fully Qualified Name of the class this Entity is an instance of. + /// </summary> + /// <value>The Fully Qualified Name of the class this Entity is an instance of.</value> public string ClassName { get { return _className; } } *************** *** 218,222 **** --- 273,294 ---- [NonSerialized] internal bool dorecreate; internal bool initialized; + + /// <summary> + /// The <see cref="CollectionPersister"/> that is currently responsible + /// for the Collection. + /// </summary> + /// <remarks> + /// This is set when NHibernate is updating a reachable or an + /// unreachable collection. + /// </remarks> [NonSerialized] internal CollectionPersister currentPersister; + + /// <summary> + /// The <see cref="CollectionPersister"/> when the Collection was loaded. + /// </summary> + /// <remarks> + /// This can be <c>null</c> if the Collection was not loaded by NHibernate and + /// was passed in along with a transient object. + /// </remarks> [NonSerialized] internal CollectionPersister loadedPersister; [NonSerialized] internal object currentKey; *************** *** 225,228 **** --- 297,307 ---- internal string role; + /// <summary> + /// Initializes a new instance of <see cref="CollectionEntry"/>. + /// </summary> + /// <remarks> + /// The CollectionEntry is for a Collection that is not dirty and + /// has already been initialized. + /// </remarks> public CollectionEntry() { *************** *** 231,234 **** --- 310,319 ---- } + /// <summary> + /// Initializes a new instance of <see cref="CollectionEntry"/>. + /// </summary> + /// <param name="loadedPersister">The <see cref="CollectionPersister"/> that persists this Collection type.</param> + /// <param name="loadedID">The identifier of the Entity that is the owner of this Collection.</param> + /// <param name="initialized">A boolean indicating if the collection has been initialized.</param> public CollectionEntry(CollectionPersister loadedPersister, object loadedID, bool initialized) { *************** *** 239,242 **** --- 324,337 ---- } + /// <summary> + /// Initializes a new instance of <see cref="CollectionEntry"/>. + /// </summary> + /// <param name="cs">The <see cref="ICollectionSnapshot"/> from another <see cref="ISession"/>.</param> + /// <param name="factory">The <see cref="ISessionFactoryImplementor"/> that created this <see cref="ISession"/>.</param> + /// <remarks> + /// This takes an <see cref="ICollectionSnapshot"/> from another <see cref="ISession"/> and + /// creates an entry for it in this <see cref="ISession"/> by copying the values from the + /// <c>cs</c> parameter. + /// </remarks> public CollectionEntry(ICollectionSnapshot cs, ISessionFactoryImplementor factory) { *************** *** 248,254 **** } ! //default behavior; will be overridden in deep lazy collections public virtual bool IsDirty(PersistentCollection coll) { if ( dirty || ( !coll.IsDirectlyAccessible && !loadedPersister.ElementType.IsMutable --- 343,361 ---- } ! /// <summary> ! /// Checks to see if the <see cref="PersistentCollection"/> has had any changes to the ! /// collections contents or if any of the elements in the collection have been modified. ! /// </summary> ! /// <param name="coll"></param> ! /// <returns><c>true</c> if the <see cref="PersistentCollection"/> is dirty.</returns> ! /// <remarks> ! /// default behavior; will be overridden in deep lazy collections ! /// </remarks> public virtual bool IsDirty(PersistentCollection coll) { + // if this has already been marked as dirty or the collection can not + // be directly accessed (ie- we can guarantee that the NHibernate collection + // wrappers are used) and the elements in the collection are not mutable + // then return the dirty flag. if ( dirty || ( !coll.IsDirectlyAccessible && !loadedPersister.ElementType.IsMutable *************** *** 259,266 **** --- 366,379 ---- else { + // need to have the coll determine if it is the same as the snapshot + // that was last taken. return !coll.EqualsSnapshot( loadedPersister.ElementType ); } } + /// <summary> + /// Prepares this CollectionEntry for the Flush process. + /// </summary> + /// <param name="collection">The <see cref="PersistentCollection"/> that this CollectionEntry will be responsible for flushing.</param> public void PreFlush(PersistentCollection collection) { *************** *** 275,278 **** --- 388,393 ---- } + // reset all of these values so any previous flush status + // information is cleared from this CollectionEntry doupdate = false; doremove = false; *************** *** 282,285 **** --- 397,405 ---- } + /// <summary> + /// Updates the CollectionEntry to reflect that the <see cref="PersistentCollection"/> + /// has been initialized. + /// </summary> + /// <param name="collection">The initialized <see cref="PersistentCollection"/> that this Entry is for.</param> public void PostInitialize(PersistentCollection collection) { *************** *** 288,298 **** } ! // called after a *successful* flush public void PostFlush(PersistentCollection collection) { if( !processed ) { throw new AssertionFailure("Hibernate has a bug processing collections"); } loadedKey = currentKey; SetLoadedPersister( currentPersister ); --- 408,426 ---- } ! /// <summary> ! /// Updates the CollectionEntry to reflect that it is has been successfully flushed to the database. ! /// </summary> ! /// <param name="collection">The <see cref="PersistentCollection"/> that was flushed.</param> public void PostFlush(PersistentCollection collection) { + // the CollectionEntry should be processed if we are in the PostFlush() if( !processed ) { throw new AssertionFailure("Hibernate has a bug processing collections"); } + + // now that the flush has gone through move everything that is the current + // over to the loaded fields and set dirty to false since the db & collection + // are in synch. loadedKey = currentKey; SetLoadedPersister( currentPersister ); *************** *** 304,307 **** --- 432,437 ---- collection.PostFlush(); + // if it was initialized or any of the scheduled actions were performed then + // need to resnpashot the contents of the collection. if ( initialized && ( doremove || dorecreate || doupdate ) ) { *************** *** 310,325 **** } ! public bool Dirty ! { ! get { return dirty; } ! } public object Key { get { return loadedKey; } } public string Role { get { return role; } } public object Snapshot { --- 440,455 ---- } ! #region Engine.ICollectionSnapshot Members ! public object Key { get { return loadedKey; } } + public string Role { get { return role; } } + public object Snapshot { *************** *** 327,340 **** } public bool SnapshotIsEmpty { ! get { //TODO: implementation here is non-extensible ... //should use polymorphism ! // return initialized && snapshot!=null && ( ! // ( snapshot is IList && ( (IList) snapshot ).Count==0 ) || // if snapshot is a collection ! // ( snapshot is Map && ( (Map) snapshot ).Count==0 ) || // if snapshot is a map ! // (snapshot.GetType().IsArray && ( (Array) snapshot).Length==0 )// if snapshot is an array ! // ); // TODO: in .NET an IList, IDictionary, and Array are all collections so we might be able --- 457,505 ---- } + public bool Dirty + { + get { return dirty; } + } + + public void SetDirty() + { + dirty = true; + } + public bool IsInitialized + { + get { return initialized;} + } + + + #endregion + + /// <summary> + /// Sets the information in this CollectionEntry that is specific to the + /// <see cref="CollectionPersister"/>. + /// </summary> + /// <param name="persister"> + /// The <see cref="CollectionPersister"/> that is + /// responsible for the Collection. + /// </param> + private void SetLoadedPersister(CollectionPersister persister) + { + loadedPersister = persister; + if (persister!=null) + { + role=persister.Role; + } + } + public bool SnapshotIsEmpty { ! get ! { //TODO: implementation here is non-extensible ... //should use polymorphism ! // return initialized && snapshot!=null && ( ! // ( snapshot is IList && ( (IList) snapshot ).Count==0 ) || // if snapshot is a collection ! // ( snapshot is Map && ( (Map) snapshot ).Count==0 ) || // if snapshot is a map ! // (snapshot.GetType().IsArray && ( (Array) snapshot).Length==0 )// if snapshot is an array ! // ); // TODO: in .NET an IList, IDictionary, and Array are all collections so we might be able *************** *** 347,370 **** } } - - public void SetDirty() - { - dirty = true; - } - - private void SetLoadedPersister(CollectionPersister persister) - { - loadedPersister = persister; - if (persister!=null) role=persister.Role; - } - - public bool IsInitialized - { - get { return initialized;} - } - public bool IsNew { ! // TODO: is this correct implementation get { return initialized && (snapshot==null); } } --- 512,518 ---- } } public bool IsNew { ! // TODO: is this correct implementation - h2.0.3 get { return initialized && (snapshot==null); } } Index: ScheduledInsertion.cs =================================================================== RCS file: /cvsroot/nhibernate/nhibernate/src/NHibernate/Impl/ScheduledInsertion.cs,v retrieving revision 1.3 retrieving revision 1.4 diff -C2 -d -r1.3 -r1.4 *** ScheduledInsertion.cs 28 Nov 2004 03:13:44 -0000 1.3 --- ScheduledInsertion.cs 29 Nov 2004 04:45:51 -0000 1.4 *************** *** 6,10 **** namespace NHibernate.Impl { ! internal class ScheduledInsertion : ScheduledEntityAction { --- 6,12 ---- namespace NHibernate.Impl { ! /// <summary> ! /// A scheduled insertion of an object. ! /// </summary> internal class ScheduledInsertion : ScheduledEntityAction { |