Telerik OpenAccess Classic

Telerik OpenAccess ORM Send comments on this topic.
Working with the Container Objects
Programmer's Guide > OpenAccess ORM Classic (Old API) > Programming With OpenAccess > The OpenAccess ORM Disconnected API > Working with the Container Objects

Glossary Item Box

This documentation article is a legacy resource describing the functionality of the deprecated OpenAccess Classic only. The contemporary documentation of Telerik OpenAccess ORM is available here.

The container is responsible for object change tracking and has knowledge of the states of the objects it contains. For example, modified objects are marked as "dirty", i.e., they would be copied back to the database when the container is copied back. Similar to the object scope, the container provides the Add() and Remove() methods to add new objects and remove objects from the container and, consequently, to and from the database. The container maintains persistence-by-reachability; the container's Add() method also adds objects referenced from the new object to the container. And, when you create a reference to a new object from an object already in the container, the new object is added to the container.

Removing an object from a container behaves a bit differently from the object scope functionality, in that the removed object remains in the container. That is, the removed object is removed from all the named lists (see below), however, it is still visible while using GetObjectbyId() or by the ObjectContainer.Count property. This behavior is necessary for resolving any potential conflicts when the container is later returned to the database.

Named Lists

While working with an object container, you will often be working with specific objects and object graphs. You have already seen how to import objects and object graphs using the ObjectContainer.CopyFrom() method. As an aid to later retrieving specific objects you have copied to the container, OpenAccess ORM provides named lists of objects. When you use the CopyFrom() method with an object or IEnumerable instance, the object or objects can automatically be added to a list with a user-specified name.

To retrieve the objects of a named list, you can obtain the list using the ObjectContainer.NamedList() method, by passing the correct list name. This allows for multiple lists of objects inside the container. All list names can be obtained from the ObjectContainer by the GetListNames() method.

To obtain all objects reachable from all named lists the following code can be used:

C# Copy Code
IEnumerator nameIter = container.GetListNames();
while (nameIter.Move())
{
	string name = (string)nameIter.Current();
	IList list = container.NamedList(name);
	foreach(object perObj in list)
	{
		Console.WriteLine(name + ":" + persObj.ToString());
	}
}
VB .NET Copy Code
Dim nameIter As IEnumerator = container.GetListNames()
Do While nameIter.Move()
  Dim name As String = CStr(nameIter.Current())
  Dim list As IList = container.NamedList(name)
  For Each perObj As Object In list
   Console.WriteLine(name & ":" & persObj.ToString())
  Next perObj
Loop

A single object in the container is reachable by multiple named lists, but a single list will contain at the most only one reference to a specific database object.

Container Object States

The objects in the container exist in a particular state. The following lists the possible container object states:

DELETED
 

When you call the container Remove() method, the object is moved to this state but not actually removed from the container. The object remains in the container in order to check for any conflicts in the container CopyTo() operation. If there are no conflicts, then the deleted container objects are also removed from the database during the CopyTo() operation.

DETACHED
 

An object in this state in the container is "hollow". Hollow objects in the container are also referred to as proxy objects. A proxy contains no data and therefore, cannot be resolved in the container. The container representation is detached from the object data. It exists only for the completeness of an object graph. For example, if you call the container CopyFrom() method for a single object that has references to other objects, the referenced objects will exist in the container as proxies. Proxy objects are not included in the CopyTo() operation.

DIRTY
 

When you modify an object in the container, it is moved to this state. You can also explicitly mark a container object as dirty with the ObjectContainer method MakeDirty( obj ). Dirty objects will be updated in the database during the CopyTo() operation.

NEW
 

Objects in this state have been created in the container and have no corresponding database object. New objects will be copied to the database during the CopyTo()

The container provides methods to interrogate the object states. A quick list of these methods follows:

bool IsRemoved( object containerObject )
Returns true if the containerObject is in the DELETED state. Deleted objects are also removed from the database in the CopyTo() operation.
bool IsHollow( object containerObject )
Returns true if the containerObject in the DETACHED state. Values of objects which are in the detached state cannot be read. When a read or write access is attempted, an exception will be thrown.
bool IsDirty( object containerObject )
Returns true if the containerObject has been modified or has been explicitly marked as dirty. Objects in the DIRTY state will be updated in the database during the CopyTo() operation.
bool IsNew( object containerObject )
Returns true if the containerObject has been created in the container and has no corresponding database object. The object is in the container NEW state. New objects will be copied to the database during the CopyTo() operation.

Container Properties

The ObjectContainer class provides properties that allow you to get information about the container. A brief list of the frequently used properties follows:

Count
 

This returns the total number of objects in the container. Objects in all object states, including objects marked as removed, are counted (Objects states are described above):

C# Copy Code
ObjectContainer container = new ObjectContainer();
int containerCount = container.Count;
// containerCount == 0
container.Add( new Address() );
containerCount = container.Count;
// containerCount == 1
VB .NET Copy Code
Dim container As New ObjectContainer()
Dim containerCount As Integer = container.Count
' containerCount == 0
container.Add(New Address())
containerCount = container.Count
' containerCount == 1

 

IsReadOnly
 

This property allows you to determine or set the container read-only setting. If the value is true, modifications to the container are not allowed. Attempting to modify a container set to read-only results in a UserException. The container is considered modified if any of the container objects are modified, if a new object is added, or an object is removed. You can set or unset the IsReadOnly property as often as you want during the life of the container:

C# Copy Code
ObjectContainer container = new ObjectContainer();
bool containerReadOnly = container.IsReadOnly;
// containerReadOnly == false
container.IsReadOnly = true;
containerReadOnly = container.IsReadOnly;
// containerReadOnly == true
VB .NET Copy Code
Dim container As New ObjectContainer()
Dim containerReadOnly As Boolean = container.IsReadOnly
' containerReadOnly == false
container.IsReadOnly = True
containerReadOnly = container.IsReadOnly
' containerReadOnly == true