Menu
▾
▴
[Jcframework-commits] dotnet AtomsFramework.xml,1.12,1.13 CInjectedObject.vb,1.29,1.30 CInjectedObjects.vb,1.9,1.10
|
From: Richard B. <rb...@us...> - 2005-05-23 07:24:07
|
Update of /cvsroot/jcframework/dotnet In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv561 Modified Files: AtomsFramework.xml CInjectedObject.vb CInjectedObjects.vb Log Message: More documentation Index: CInjectedObject.vb =================================================================== RCS file: /cvsroot/jcframework/dotnet/CInjectedObject.vb,v retrieving revision 1.29 retrieving revision 1.30 diff -u -d -r1.29 -r1.30 --- CInjectedObject.vb 20 May 2005 06:03:40 -0000 1.29 +++ CInjectedObject.vb 23 May 2005 07:23:55 -0000 1.30 @@ -91,7 +91,7 @@ ''' <summary> ''' An original copy of the object before changes were made. ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -302,6 +302,7 @@ ''' <param name="name">The attribute name (property name)</param> ''' <returns>An object or nothing</returns> ''' <remarks>Uses the CallByName method to get the value for a property of the object. + ''' </remarks> ''' <history> ''' [rbanks] 20/05/2005 Created ''' </history> @@ -317,6 +318,7 @@ ''' <param name="name">The attribute name (property name)</param> ''' <returns>An object or nothing</returns> ''' <remarks>Uses the CallByName method to get the value for a property of the object. + ''' </remarks> ''' <history> ''' [rbanks] 20/05/2005 Created ''' </history> @@ -328,7 +330,7 @@ ''' <summary> ''' Indicates wether Associations have been loaded for the ReferencedObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -340,7 +342,7 @@ If Me.GetClassMap.AssociationMapCount > 0 Then Return m_associationsLoaded Else - 'If the class has no associations then associations are already "loaded" + 'If the class has no associations then associations are already loaded 'However if the object is not persistent then the associations obviously can't be loaded yet Return Me.Persistent End If @@ -354,7 +356,7 @@ ''' <summary> ''' The expiry interval for the InjectedObject in the Cache ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks>This is the expiry interval of the object in the persistence cache, not the Injected Object Cache. ''' </remarks> ''' <history> @@ -374,7 +376,7 @@ ''' <summary> ''' Indicates wether the object has been marked for deletion. ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks>InjectedObjects must be marked for deletion before the PersistChanges method of the PersistenceBroker is called if they are ''' to be removed from the database. ''' </remarks> @@ -395,7 +397,7 @@ ''' <summary> ''' Indicates if deleting this object will also delete any of it's parent objects. ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -416,7 +418,7 @@ ''' See IPersistableObject ''' </summary> ''' <param name="propertyName"> </param> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -432,7 +434,7 @@ ''' See IPersistableObject ''' </summary> ''' <param name="propertyName"> </param> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -519,7 +521,7 @@ ''' <summary> ''' Indicates that the ReferencedObject has changed and requires saving to the database. ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -545,7 +547,7 @@ ''' <summary> ''' Inidicates if the ReferencedObject is being loaded from the database ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -568,7 +570,7 @@ ''' <summary> ''' See IPersistableObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -588,7 +590,7 @@ ''' <summary> ''' See IPersistableObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -605,7 +607,7 @@ ''' <summary> ''' See IPersistableObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -625,7 +627,7 @@ ''' <summary> ''' See IPersistableObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -642,7 +644,7 @@ ''' <summary> ''' See IPersiatableObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -670,7 +672,7 @@ ''' <summary> ''' See IPersistableObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> @@ -690,7 +692,7 @@ ''' <summary> ''' See IPersistableObject ''' </summary> - ''' <returns></returns> + ''' <returns> </returns> ''' <remarks> ''' </remarks> ''' <history> Index: AtomsFramework.xml =================================================================== RCS file: /cvsroot/jcframework/dotnet/AtomsFramework.xml,v retrieving revision 1.12 retrieving revision 1.13 diff -u -d -r1.12 -r1.13 --- AtomsFramework.xml 20 May 2005 06:03:36 -0000 1.12 +++ AtomsFramework.xml 23 May 2005 07:23:55 -0000 1.13 @@ -4111,7 +4111,7 @@ <summary> An original copy of the object before changes were made. </summary> - <returns /> + <returns> </returns> <remarks> </remarks> <history> @@ -4194,68 +4194,86 @@ <param name="name">The attribute name (property name)</param> <returns>An object or nothing</returns> [...4838 lines suppressed...] </summary> <remarks>Manages the references to the singleton <see cref="T:AtomsFramework.OIDFactory" /> object.</remarks> <history> [rbanks] 18/12/2003 Created - </history></member><member name="M:AtomsFramework.modObjectIdFactorySingleton.GetOidFactoryInstance"><summary> + </history></member> + <member name="M:AtomsFramework.modObjectIdFactorySingleton.GetOidFactoryInstance"> + <summary> Gets a reference to the OIDFactory instance. </summary> <returns>A reference to the OIDFactory object.</returns> @@ -8010,6 +9140,6 @@ exist it is created.</remarks> <history> [rbanks] 18/12/2003 Created - </history></member></remarks></member></remarks></member> + </history></member> </members> </doc> \ No newline at end of file Index: CInjectedObjects.vb =================================================================== RCS file: /cvsroot/jcframework/dotnet/CInjectedObjects.vb,v retrieving revision 1.9 retrieving revision 1.10 diff -u -d -r1.9 -r1.10 --- CInjectedObjects.vb 11 Apr 2005 00:31:43 -0000 1.9 +++ CInjectedObjects.vb 23 May 2005 07:23:55 -0000 1.10 @@ -3,12 +3,43 @@ 'Injected object keys are hashed on the object itself, not the value of the object '(unlike the persistence brokers cache which works via key values) +''' ----------------------------------------------------------------------------- +''' Project : AtomsFramework +''' Class : InjectedObjectKey +''' +''' ----------------------------------------------------------------------------- +''' <summary> +''' Maintains information about the key fields of each injected object +''' </summary> +''' <remarks>This class stores information from the key properties of the objects in the +''' cache. Since objects can have multiple key fields of different types the InjectedObjectKey class +''' is written in a fairly generic manner. +''' <para>It maintains a collection of key values (all of which must be non-null) and +''' uses them to generate a hashcode. This hashcode is then used as the key to +''' the particular cache entry in question.</para> +''' <para>It is very similar to the CacheKey used for persistence caching.</para> +''' </remarks> +''' <history> +''' [rbanks] 23/05/2005 Created +''' </history> +''' ----------------------------------------------------------------------------- Public Class InjectedObjectKey Private m_hashCode As Integer Private m_type As Type Private m_keyvalues As Collection Private m_istemporary As Boolean + '''----------------------------------------------------------------------------- + ''' <summary> + ''' Creates a new instance of the InjectedObjectKey class + ''' </summary> + ''' <param name="obj">The object we are generating a key for.</param> + ''' <remarks>Creates a new injected object key entry based on the key fields in the object. Works + ''' regardless of wether the object uses ObjectID's or has it's own key fields.</remarks> + ''' <history> + ''' [rbanks] 27/11/2003 Created + ''' </history> + '''----------------------------------------------------------------------------- Public Sub New(ByVal obj As Object) If obj Is Nothing Then Throw New AtomsFrameworkException("Cannot create injected objects using Null objects") @@ -22,6 +53,19 @@ End If End Sub + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Indicates wether this injected object is transient + ''' </summary> + ''' <value>True if the cache key is short lived.</value> + ''' <remarks>Some persistence transaction require the creation and tracking objects that are + ''' not explicitly tracked by the developer. The framework will track these objcets internally and mark them as + ''' Temporary objects. Once the transaction is completed the temporary entries are removed. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Property Temporary() As Boolean Get Return m_istemporary @@ -31,6 +75,17 @@ End Set End Property + '''----------------------------------------------------------------------------- + ''' <summary> + ''' Populates a new instance of the InjectedObjectKey class with an existing injected object. + ''' </summary> + ''' <param name="injObj">The object we are generating a key for.</param> + ''' <remarks>Populates or replaces the contents of the InjectedObjectKey with the values from the passed in InjectedObject. + ''' </remarks> + ''' <history> + ''' [rbanks] 27/11/2003 Created + ''' </history> + '''----------------------------------------------------------------------------- Public Sub NewInjObj(ByVal injObj As InjectedObject) If injObj Is Nothing Then Throw New AtomsFrameworkException("Cannot track null objects") @@ -42,35 +97,34 @@ PopulateKey(injObj) End Sub + '''----------------------------------------------------------------------------- + ''' <summary> + ''' Obtains a hash code for the current object + ''' </summary> + ''' <returns>A hash code for the current object</returns> + ''' <remarks>The hash code is identical to the hash code of the source object. + ''' </remarks> + ''' <history> + ''' [rbanks] 27/11/2003 Created + ''' </history> + '''----------------------------------------------------------------------------- Public Overrides Function GetHashCode() As Integer Return m_hashCode End Function - 'Private Sub CalculateHashCode() - ' Dim i As Long - ' Dim count As Integer - ' Dim obj As Object - ' Dim t As Type - ' i = m_type.Name.GetHashCode - ' count = 1 - ' For Each obj In m_keyvalues - ' If Not obj Is Nothing Then - ' If TypeOf obj Is Integer Then - ' i += CInt(obj).GetHashCode - ' ElseIf TypeOf obj Is String Then - ' i += CStr(obj).GetHashCode - ' ElseIf TypeOf obj Is Double Then - ' i += CDbl(obj).GetHashCode - ' Else - ' t = obj.GetType - ' i += t.Name.GetHashCode - ' End If - ' count += 1 - ' End If - ' Next - ' m_hashCode = CInt(i / count) - 'End Sub - + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Populates the InjectedObjectKey with values from an IPersistableObject + ''' </summary> + ''' <param name="injObj">The source object</param> + ''' <remarks>The key values from the source object are copied to the InjectedObjectKey and used for tracking the object. + ''' </remarks> + ''' <exception cref="AtomsFramework.AtomsFrameworkException">A key value is null. All key values must have non-null values. + ''' </exception> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Protected Sub PopulateKey(ByVal injObj As IPersistableObject) Dim cm As ClassMap Dim i As Short @@ -93,9 +147,20 @@ m_keyvalues.Add(x) Next m_hashCode = injObj.GetSourceObject.GetHashCode - 'CalculateHashCode() End Sub + '''----------------------------------------------------------------------------- + ''' <summary> + ''' Determines if two InjectedObjectKey objects are equivalent. + ''' </summary> + ''' <param name="obj1">The first object to compare</param> + ''' <param name="obj2">The second object to compare</param> + ''' <returns>Boolean indicating equivalence</returns> + ''' <remarks>Comparison is made based on hash code values.</remarks> + ''' <history> + ''' [rbanks] 27/11/2003 Created + ''' </history> + '''----------------------------------------------------------------------------- Public Overloads Shared Function Equals(ByVal obj1 As Object, ByVal obj2 As Object) As Boolean Dim key1, key2 As InjectedObjectKey key1 = CType(obj1, InjectedObjectKey) @@ -103,6 +168,18 @@ Return key1.Equals(key2) End Function + '''----------------------------------------------------------------------------- + ''' <summary> + ''' Determines if the key for an object is equivalent to the current cache key. + ''' </summary> + ''' <param name="obj">The object to be compared</param> + ''' <returns>Boolean indicating equality</returns> + ''' <remarks>The comparison is made based on the referenced object type and on the + ''' hash key values.</remarks> + ''' <history> + ''' [rbanks] 27/11/2003 Created + ''' </history> + '''----------------------------------------------------------------------------- Public Overloads Overrides Function Equals(ByVal obj As Object) As Boolean Dim key As InjectedObjectKey key = obj @@ -115,6 +192,17 @@ Return True End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' A string representation of the InjectedObjectKey object + ''' </summary> + ''' <returns> </returns> + ''' <remarks> + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overrides Function ToString() As String Dim s As String Dim obj As Object @@ -145,12 +233,43 @@ End Function End Class - +''' ----------------------------------------------------------------------------- +''' Project : AtomsFramework +''' Class : InjectedObjectCache +''' +''' ----------------------------------------------------------------------------- +''' <summary> +''' The Cache for InjectedObjects. +''' </summary> +''' <remarks>The InjectedObjectCache is a collection of InjectedObjects and matching InjectedObjectKeys based on a +''' standard hash table. +''' <para>The InjectedObject cache is a little difficult to explain, but in simple terms we need to keep track of each object +''' we wish to persist regardless of wether it is inheriting from PersistentObject or not. If it not (a non-inheited object) then we wrap +''' it up in an InjectedObject class and keep track of it using this cache.</para> +''' <para>By doing so we are able to keep track of it's state, dirtiness, etc and we can treat it internally much the same as an +''' inherited object.</para> +''' </remarks> +''' <history> +''' [rbanks] 23/05/2005 Created +''' </history> +''' ----------------------------------------------------------------------------- Public Class InjectedObjectCache Inherits System.Collections.Hashtable Private m_lastFoundKey As InjectedObjectKey + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Adds an InjectedObject to the cache, allowing the setting of the temporary flag. + ''' </summary> + ''' <param name="obj">The object to add</param> + ''' <param name="temporary">A flag to indicate if the object is only being added temporarily</param> + ''' <remarks> + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Sub AddTemp(ByVal obj As InjectedObject, ByVal temporary As Boolean) Dim injKey As InjectedObjectKey @@ -172,10 +291,33 @@ End If End Sub + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Add an InjectedObject to the cache. + ''' </summary> + ''' <param name="obj">The object to add.</param> + ''' <remarks>The object is added permanently. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Sub Add(ByVal obj As InjectedObject) Me.AddTemp(obj, False) End Sub + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Checks if an InjectedObject is already present in the cache. + ''' </summary> + ''' <param name="obj">The object to find.</param> + ''' <returns>Boolean indicating if the object is in the cache.</returns> + ''' <remarks>The find() method is called to try and locate the object and the result is interpreted as a boolean return value. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Function IsTracked(ByVal obj As Object) As Boolean Dim injObj As InjectedObject injObj = Find(obj) @@ -186,6 +328,20 @@ End If End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Determine if an InjectedObject exists in the cache. + ''' </summary> + ''' <param name="obj">The object to find</param> + ''' <param name="useFindAttributes">Wether to use Find attributes or Key attributes.</param> + ''' <returns>A boolean indicating success or failure</returns> + ''' <remarks>The useFindAttributes parameter determines if the object should be searched for using Find attributes or KeY + ''' attribtues. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Function Exists(ByVal obj As InjectedObject, ByVal useFindAttributes As Boolean) As Boolean If Find(obj, useFindAttributes) Is Nothing Then Return False @@ -194,10 +350,35 @@ End If End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Find an object in the cache + ''' </summary> + ''' <param name="obj">An object to find</param> + ''' <returns>Boolean indicating success or failure</returns> + ''' <remarks> + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Function Find(ByVal obj As Object) As InjectedObject Return Find(obj, False) End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Find an object in the cache + ''' </summary> + ''' <param name="obj">An object to find</param> + ''' <param name="useFindAttributes">Wether to use Find attributes or Key attributes</param> + ''' <returns>Boolean indicating success or failure</returns> + ''' <remarks> + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Function Find(ByVal obj As Object, ByVal useFindAttributes As Boolean) As InjectedObject Dim injObj As InjectedObject If Not TypeOf (obj) Is InjectedObject Then @@ -208,10 +389,38 @@ Return Find(injObj, useFindAttributes) End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Find an InjectedObject in the cache + ''' </summary> + ''' <param name="obj">The InjectedObject to find.</param> + ''' <param name="useFindAttributes">Wether to use Find attributes or Key attributes</param> + ''' <returns>Boolean indicating success or failure.</returns> + ''' <remarks> + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Function Find(ByVal obj As InjectedObject, ByVal useFindAttributes As Boolean) As InjectedObject Return Find(obj, useFindAttributes, True) End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Find an InjectedObject in the cache + ''' </summary> + ''' <param name="obj">The InjectedObject to find</param> + ''' <param name="useFindAttributes">Wether to use Find attributes or Key attributes</param> + ''' <param name="checkSubclasses">Wether to check child classes for a match.</param> + ''' <returns>A boolean indicating success or failure.</returns> + ''' <remarks>Comparisons are made using the indicated attributes only, not using non-key attributes. It is possible for two objects that are + ''' different to still produce a match if the key/find values are equivalent. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Function Find(ByVal obj As InjectedObject, ByVal useFindAttributes As Boolean, ByVal checkSubclasses As Boolean) As InjectedObject Dim injObj As InjectedObject Dim x As DictionaryEntry @@ -248,7 +457,7 @@ ' m_Enumerator.Reset() 'Reset enumerator after removing item 'Else found = True - If t Is obj.GetObjectType OrElse (checkSubClasses AndAlso t.IsSubclassOf(obj.GetObjectType)) Then + If t Is obj.GetObjectType OrElse (checkSubclasses AndAlso t.IsSubclassOf(obj.GetObjectType)) Then Try If useFindAttributes Then For i = 1 To cm.GetFindSize @@ -282,6 +491,17 @@ Return Nothing End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Remove an InjectedObject from the cache + ''' </summary> + ''' <param name="obj">The object to remove</param> + ''' <remarks>If the object is not found no exception is thrown. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overloads Sub Remove(ByVal obj As InjectedObject) If obj Is Nothing Then Exit Sub @@ -297,6 +517,16 @@ End Try End Sub + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Clean the cache after a transaction + ''' </summary> + ''' <remarks>Removes temporary cache entries and resets the IsQueued flag for all entries. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Sub CleanUp() 'Clean up cache by resetting isqueued flags, removing temp entries, and clearing strong references Dim toRemove As New Collection @@ -339,6 +569,17 @@ Next End Sub + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' String representation of the InjectedObjectCache contents + ''' </summary> + ''' <returns> </returns> + ''' <remarks> + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Overrides Function ToString() As String Dim x As DictionaryEntry Dim injObj As InjectedObject @@ -361,6 +602,17 @@ Return outString End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Get an ArrayList copy of the cache. + ''' </summary> + ''' <returns> </returns> + ''' <remarks>Useful for debugging purposes only. Should not be used for anything else. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Function GetValueArray() As ArrayList Dim al As ArrayList If Me.Values.Count = 0 Then Return New ArrayList @@ -370,6 +622,17 @@ Return al End Function + ''' ----------------------------------------------------------------------------- + ''' <summary> + ''' Get an ArrayList copy of the InjectedObjectKeys for the cache + ''' </summary> + ''' <returns> </returns> + ''' <remarks>Useful for debugging only. Should not be used for anything else. + ''' </remarks> + ''' <history> + ''' [rbanks] 23/05/2005 Created + ''' </history> + ''' ----------------------------------------------------------------------------- Public Function GetKeyArray() As ArrayList Dim al As ArrayList If Me.Keys.Count = 0 Then Return New ArrayList |
