Generated code - Using the context, Adapter

Preface

Selfservicing and Adapter both support so called uniquing contexts, it allows you to make sure that one entity class instance per loaded entity instance is known in your semantic context (e.g. method, object), as the runtime framework makes it possible to load a given entity with a given PK multiple times, each time in a new entity class instance. These contexts, implemented in the Context class, available in the ORM Support classes, represent a semantic context in your program. Within these semantic contexts, the representing Context object assures that an entity instance (the data) loaded by the framework is loaded in just one entity class instance. This is e.g. required for re-fetching trees of objects using prefetch paths, or for situations where more than one object with the same data is problematic.

This section discusses the Context object more in detail. It is not strictly necessary to use a Context object in your application, e.g. in state-less environments like ASP.NET it's not of much use. Though it can sometimes be required to have just one entity class instance with a given entity's data in a given semantic context, e.g. in an edit form in a windows forms application.

The Context class

When you pass an entity instance using remoting or webservices to a server which then returns it back after processing, you won't reference the same instance of the entity class you sent to the server. This is because of the serialization and deserialization which takes place during remoting or using webservices. The Context class identifies entity instances (the data) using the PK field values. New entities aren't directly added to the Context's internal object cache, as for example Identity columns won't have a value for the PK field until they're saved and the transaction has been committed. When an entity is saved and the transaction is committed (if any), the entity class instance the entity data is in is added to the Context's cache if the entity is new. A non-new entity which is added to a Context object, is directly added to the Context's internal object cache, if the entity class instance hasn't been added to another Context already.

Entity class instances can be added to the Context at any time, as well as entity collections. When an entity class instance is added to a Context, its internally referenced related entity class instances and entity collection objects are added to the same Context object as well. When an entity collection is added to a Context object, all its contained entity class instances will be added to the Context and every entity class instance added to the entity collection after that point will be added to the same Context object the collection is added to as well, which makes it easy to work with a Context object, as it is mostly transparent.

The Context objects don't act as a cache which is used to prevent database activity. Every query is still executed on the database. If an entity instance is already loaded in the used Context object, the entity data read from the database is not added to a new entity class instance, but the entity class instance already known by the context containing the same entity instance is updated. If the already known class instance is marked as dirty, the data isn't updated and the loaded entity data is simply skipped and the already known entity class instance is returned as is. This is done in the Get method of the Context object. The Context has a flag to disallow this particular action: SetExistingEntityFieldsInGet. See the LLBLGen Pro reference manual for details on this flag.

You can of course use the Context as an object cache for single entity fetches, though keep in mind that a Context object is simply acting as a unique entity class instance supplier (one entity class instance per loaded entity instance), it doesn't fetch entities from the database, so if you request an entity instance from a Context object using Get and the Context object can't find it in its cache, you have to test if the returned entity class instance does indeed contain a fetched entity instance (entity.IsNew is false) or a new entity class instance (entity.IsNew is true).

Adding an entity class instance which is already present in the Context is a no-op, as well as when an entity class instance is already part of another Context object. After an entity is added to a Context object, and a 1:1/m:1 reference is set to an entity class instance, the related entity is not added to the Context automatically, this has to be done manually by the developer, though when an entity is added to a collection which is added to a context, the entity is added to that Context as well. The Context object an entity is added to is returned by the entity's ActiveContext property.

When an entity is deleted, the status of the entity is set to Deleted by the delete methods. The Context.Get method will remove an entity from its internal cache if the entity is deleted and not participating in a transaction.

Using the Context class

The Context class should be seen as a convenience providing class for uniquing within a semantic context. It shouldn't be confused with a Unit of Work + Object Fetch object, because it leaves that functionality to other objects and methods.
Retrieving instances from a Context
A Context object supplies a Get method which offers different ways to retrieve the already loaded instance for a given entity. As a Context object uses the value(s) of the PK field(s), you can use this to retrieve the unique instance. Below are the different ways illustrated: it will try to retrieve the instance which already contains the entity data for the customer with CustomerID "CHOPS".

// C#
// using a factory
CustomerEntity c = (CustomerEntity)myContext.Get(new CustomerEntityFactory(), "CHOPS");

// using a fetched entity
CustomerEntity c = new CustomerEntity("CHOPS");
adapter.FetchEntity(c);
cc = (CustomerEntity)myContext.Get(c);
' VB.NET
' using a factory
Dim c As CustomerEntity = CType(myContext.Get(new CustomerEntityFactory(), "CHOPS"), CustomerEntity)

' using a fetched entity
Dim c As New CustomerEntity("CHOPS")
adapter.FetchEntity(c)
c = CType(myContext.Get(c), CustomerEntity)
Single entity fetches
To be able to load the entity's data into a new entity class instance if the Context used doesn't have an instance with that data present and just return the already loaded instance if the Context does have an instance of the entity class with the entity data, use the construct mentioned above:

//// C#
CustomerEntity c = new CustomerEntity("CHOPS");  // A
adapter.FetchEntity(c);
c = (CustomerEntity)myContext.Get(c);
// At this point, 'c' is either the newly instance we created in line A if myContext didn't know the
// entity 'CHOPS', otherwise 'c' is the entity class instance known by myContext which 
// contains the entity 'CHOPS'. 
' VB.NET
Dim c As New CustomerEntity("CHOPS")    ' A
adapter.FetchEntity(c)
c = CType(myContext.Get(c), CustomerEntity)
' At this point, 'c' is either the newly instance we created in line A if myContext didn't know the
' entity 'CHOPS', otherwise 'c' is the entity class instance known by myContext which 
' contains the entity 'CHOPS'.

This will fetch customer "CHOPS" from the database but the Context wiwill check if the entity instance is already available in an entity class instance in this Context. If so, it will return that entity class instance, not the newly created entity class instance. If the entity instance isn't known by the Context, it is added to the Context by adding the entity class instance (the one created on line 'A' in the example above) and the Context returns the entity class instance passed to the Get() method call (the one created on line 'A').

Entities can also be added manually first and then fetched:

//// C#
CustomerEntity c = new CustomerEntity("CHOPS");
myContext.Add(c);
adapter.FetchEntity(c);
' VB.NET
Dim c A New CustomerEntity()
myContext.Add(c)
adapter.FetchEntity(c)

Or, using a unique constraint:

//// C#
CustomerEntity c = new CustomerEntity();
c.CompanyName = "Foo Inc.";
myContext.Add(c);
adapter.FetchEntityUsingUniqueConstraint(c, c.ConstructFilterForUCCompanyName());
' VB.NET
Dim c A New CustomerEntity()
c.CompanyName = "Foo Inc."
myContext.Add(c)
adapter.FetchEntityUsingUniqueConstraint(c, c.ConstructFilterForUCCompanyName())

Though it has to be understood that the actual entity instance inside the entity class instance referenced by the variable 'c' is only unique if the particular entity instance hasn't been loaded yet. This is due to the c = new CustomerEntity() line; it creates a new entity class instance so adding it to a context doesn't make it the entity class instance holding the entity instance. Fetching using unique constraints is a bit problematic in this case. To avoid that you can do:

//// C#
CustomerEntity c = new CustomerEntity();
c.CompanyName = "Foo Inc.";
myContext.Add(c);
adapter.FetchEntityUsingUniqueConstraint(c, c.ConstructFilterForUCCompanyName());
c = (CustomerEntity)myContext.Get(c);  // get unique version. No db activity.
' VB.NET
Dim c As New CustomerEntity()
c.CompanyName = "Foo Inc."
myContext.Add(c)
adapter.FetchEntityUsingUniqueConstraint(c, c.ConstructFilterForUCCompanyName())
c = CType(myContext.Get(c), CustomerEntity) ' get unique version. No db activity.
Prefetch Path fetches
Fetching an entity instance or set of entities and using a prefetch path can utilize a Context by one of the overloads of FetchEntityCollection, FetchEntity, FetchNewEntity etc., which accepts a Context object. If you're fetching a set of related entities and you want to have for every already loaded entity instance in a particular Context the instance in which the entity is already loaded, you can pass in the Context in which these entity instances are already added to. The fetch logic will then build the object graph using the instances from the passed in Context, otherwise it will read the entity instances in newly created entity class instances. Below is an example which uses a Context object to fetch additional nodes of an object graph after parts of the graph were fetched earlier: it loads additional, related entities in an existing set of entities. 

// C#
// first part, load the customer and its related order entities.
CustomerEntity customer = new CustomerEntity("BLONP");
using(DataAccessAdapter adapter = new DataAccessAdapter())
{
	Context myContext = new Context();
	PrefetchPath2 prefetchPath = new PrefetchPath2(EntityType.CustomerEntity);
	prefetchPath.Add(CustomerEntity.PrefetchPathOrders);
	adapter.FetchEntity(customer, prefetchPath, myContext);
	
	// ...
	
	// customer and its orders are now loaded.
}


// Say, later on we want to add the order details
// of each order of this customer to this graph. We can do that with the following code.
using(DataAccessAdapter adapter = new DataAccessAdapter())
{
	// re-define the prefetch path, as if we're somewhere else in the application
	PrefetchPath2 prefetchPath = new PrefetchPath2(EntityType.CustomerEntity);
	prefetchPath.Add(CustomerEntity.PrefetchPathOrders).SubPath.Add(OrderEntity.PrefetchPathOrderDetails);

	// fetch the customer again. As it is already added to a Context (myContext), the fetch logic
	// will use that Context object. This fetch action will fetch all data again, but into the same
	// entity class instances and will for each Order entity loaded, load the Order Detail entities as well.
	adapter.FetchEntity(customer, prefetchPath);
}

' VB.NET
' first part, load the customer and its related order entities.
Dim customer As New CustomerEntity("BLONP")
Using adapter As New DataAccessAdapter()
	Dim myContext As New Context()
	Dim prefetchPath As New PrefetchPath2(CInt(EntityType.CustomerEntity))
	prefetchPath.Add(CustomerEntity.PrefetchPathOrders)
	adapter.FetchEntity(customer, prefetchPath, myContext)
	
	' ...
	
	' customer and its orders are now loaded. 
End Using

' Say, later on we want to add the order details
' of each order of this customer to this graph. We can do that with the following code.
Using adapter As New DataAccessAdapter()
	' redefine the prefetch path, as if we're somewhere else in the application
	Dim prefetchPath As new PrefetchPath2(EntityType.CustomerEntity))
	prefetchPath.Add(CustomerEntity.PrefetchPathOrders).SubPath.Add(OrderEntity.PrefetchPathOrderDetails)

	' fetch the customer again. As it is already added to a Context (myContext), the fetch logic
	' will use that Context object. This fetch action will fetch all data again, but into the same
	' objects and will for each Order entity loaded load the Order Detail entities as well.
	adapter.FetchEntity(customer, prefetchPath)
End Using


note Note:
When fetching an entity collection, you've to add the collection to fetch to the context object and then call the FetchEntityCollection method. Doing so will set the collection's DoNotAddIfPresent property to true.
Entity Save calls
When an entity is saved, the DataAccessAdapter class will signal the Context the entity is in (if any), that the entity in question is saved. This allows the Context to do housekeeping on new/existing entity class instances. This takes into account running transactions, meaning that a rollback doesn't leave the Context in an undefined state, but in the state as before the transaction started.
Multi-entity activity
Actions on entity collections are seen as actions inside the active Context if the collection is first added to a context. All persistence logic will re-use objects from the Context object if the entity collection used is added to a context. SaveEntityCollection() will first add any entities saved to the context the collection is in, if the entity isn't already in the context.

Remarks

LLBLGen Pro Runtime Framework v4.0 documentation. ©2013 Solutions Design bv