The Session keeps loaded objects in the internal object storage called Identity Map. This is not a regular cache - XPO uses the identity map to ensure the consistency of objects (only a single object can be associated with a specific database record). The identity map uses Weak References to hold persistent objects in memory. When the application releases all references to an object, the .NET Garbage Collector can collect it.
The XPBaseCollection.Reload method queries the data store for all records that match the collection's Criteria. While processing the query result, XPO searches for an existing object instance in the identity map using the record's primary key.
* If an object does not exist on the map, XPO creates a new instance and populates its properties with the loaded data.
* If an object exists on a map, XPO updates the existing object only if the data was modified in the database. XPO uses the built-in Optimistic Concurrency Control feature to check if the data in the database was modified.
If the Optimistic Concurrency Control is disabled for a persistent class, the XPBaseCollection.Reload method will not update objects. XPO supports different approaches to track changes: increment the service column value on each update (OptimisticLockField), compare property values with the loaded data (use all properties), compare property values with the loaded data (use modified properties only). Refer to the corresponding article in our online documentation for details.
The Session.Reload method reloads an object and updates its properties using the loaded data. All changes made before reloading will be lost after this operation.
It is possible to force a Session to release all its objects by calling the Session.DropIdentityMap method. Taking into account that previously loaded persistent objects become invalid after this operation, we discourage using this method to reload objects. Use the dedicated methods for this purpose: XPBaseCollection.Reload, Session.Reload, Session.GetObjectByKey, Session.FindObject.
XPCollection.Reload vs. Session.Reload
The Session.Reload method sends a query to the data store and assigns the loaded values to the object's properties. This method does not reload reference properties and child collections.
The XPBaseCollection.Reload method reloads a collection (adds/removes objects if corresponding records were added/removed to/from the data store). If the Optimistic Concurrency Control is enabled, this method updates properties of an object if its record was modified in the database.
Session.FindObject vs Session.GetObjectByKey
The Session.FindObject method always searches for a record with the specified values in the data store. If found, XPO checks if the corresponding object already exists on the Identity Map. If the Optimistic Concurrency Control is enabled and the corresponding database record was modified, XPO assigns the loaded data to the object's properties. If an object does not exist in the Identity Map, XPO creates a new object instance and initializes its properties.
The Session.GetObjectByKey method searches for an object on the Identity Map first. If it is not found, it tries to load an object from the data store.
How to reload persistent objects completely (including reference properties and child collections)?
The best practice to reload everything in one step is to dispose of the Session or UnitOfWork instance, create a new one and use it to reload data (create a new XPCollection, XPView, etc.). Knowing that it is difficult to use this approach in WinForms applications, we provide the XPBindingSource component (available in version 19.1+). Use this component to build data bindings in the visual designer and set its DataSource property at runtime to load/reload data. Refer to the following example for details: How to Bind Data to WinForms Controls.