Instantiating an existing entity instance

To load the entity's data from the persistent storage, we use the generated class related to this entity's definition, create an instance of that class and order it to load the data of the particular entity. As an example we're loading the entity identified with the customerID "CHOPS" into an object.

Using the primary key value

One way to instantiate the entity in an object is by passing all primary key values to the constructor of the entity class to use:

var customer = new CustomerEntity("CHOPS");

This will load the entity with the primary key value of "CHOPS" into the object named customer, directly from the persistent storage.

Another, less compact way is to use an empty entity object and to fetch it by calling its fetch method:

var customer = new CustomerEntity();
customer.FetchUsingPK("CHOPS");

Using Linq / QuerySpec

There are other ways to fetch an entity using the PK value. LLBLGen Pro supports Linq and has its own high-level query system QuerySpec. The example below looks like the following in these two query systems.

var metaData = new LinqMetaData();
var customer = metaData.Customer.FirstOrDefault(c=>c.CustomerId=="CHOPS);

var qf = new QueryFactory();
var q = qf.Customer.Where(CustomerFields.CustomerId=="CHOPS");
CustomerEntity customer = q.GetFirst();

Using a related entity

Another way to instantiate this same entity is via a related entity using Lazy Loading. Let's load the order with ID 10254, which is an order of customer "CHOPS", and via that order, get an instance of the entity "CHOPS".

var order = new OrderEntity(10254);     // fetches the order
var customer = order.Customer;       // fetches the customer, through lazy loading

LLBLGen Pro automatically creates properties to retrieve related entities or collections of related entities, using an instance of a given entity. It doesn't matter what type the relation between the two entities has: 1:n, m:1, 1:1 or m:n. In this case, Customer and Order have an 1:n relationship (one customer can have multiple orders) from the Customer's point of view and a m:1 relationship (one Order can have just one customer) from the Order's point of view.

A single entity property, which order.Customer is, uses the method GetSingleFieldMappedOnRelation() to actually retrieve the entity. You can use that method too, instead of the property:

var order = new OrderEntity(10254);
var customer = order.GetSingleCustomer();

If Customer is in an inheritance hierarchy, the fetch is polymorphic. This means that if the order entity, in this case order 10254, has a reference to a derived type of Customer, for example GoldCustomer, the entity returned will be of type GoldCustomer. See also Polymorphic fetches below.

Using a unique constraint's value

The Customer entity in our previous example also has a unique constraint defined on its field CompanyName. We can use that field to load the same entity. Fetching the entity using a unique constraint is done via two steps: first create an empty entity object, then fetch the entity data using a method call.

Because an entity can have more than one unique constraint, these have the fields in the unique constraint in the methodnames. In the case of our example, the entity Customer has a unique constraint with one field, CompanyName, which is utilized by method FetchUsingUCCompanyName(companyName):

var customer = new CustomerEntity();
customer.FetchUsingUCCompanyName("Chop-suey Chinese");

Using a prefetch path

An easy way to instantiate an entity can be by using a Prefetch Path, to read related entities together with the entity or entities to fetch. See for more information about Prefetch Paths and how to use them: Prefetch Paths.

Using a collection class

Another way to instantiate an entity is by creating a collection class with one or more entities of the same entity definition (entity type, like Customer) using the EntityCollection classes or via a related entity which has a 1:n relation with the entity to instantiate. For an example, please see Tutorials and Examples: How Do I? - Read all entities into a collection.

Using a Context object

If you want to get a reference to an entity object already in memory, you can use a Context object, if that object was added to that particular Context object. The example below retrieves a reference to the customer object with PK "CHOPS", if that entity was previously loaded into an entity object which was added to that Context object. If the entity object isn't in the Context object, a new entity object is returned. An example usage is shown below.

var customer = (CustomerEntity)myContext.Get(new CustomerEntityFactory(), "CHOPS");
if(customer.IsNew)
{
    // not found in context, fetch from database
    customer.Refetch();
}

Polymorphic fetches

Already mentioned early in this section is the phenomenon called 'Polymorphic fetches'. Imagine the following entity setup: BoardMember entity has a relation (m:1) with CompanyCar. CompanyCar is the root of a TargetPerEntityHierarchy inheritance hierarchy and has two subtypes: FamilyCar and SportsCar.

Because BoardMember has the relationship with CompanyCar, a field called 'CompanyCar' is created in the BoardMember entity which is mapped onto the m:1 relation BoardMember - CompanyCar.

In the database, several BoardMember instances have been stored, as well as several different CompanyCar instances, of type FamilyCar or SportsCar. Using lazy loading, you can load the related CompanyCar instance of a given BoardMember's instance by simply calling the 'CompanyCar' property:

CompanyCarEntity car = myBoardMember.CompanyCar;

However, 'car' in the example above, can be of a different type. If for example the BoardMember instance in myBoardMember has a FamilyCar as company car set, 'car' is of type FamilyCar. Because the fetch action can result in multiple types, the fetch is called polymorphic. So, in our example, if 'car' is of type FamilyCar, the following code would also be correct:

FamilyCarEntity car = (FamilyCarEntity)myBoardMember.CompanyCar;

Would this BoardMember instance have a SportsCar set as company car, this code would fail at runtime with a specified cast not valid exception.

FetchPolymorphic

Each entity which is in an inheritance hierarchy has a method called FetchPolymorphic, which is a static/Shared method. This method lets you fetch an entity which is a subtype of the entity you call the method on. E.g. if CompanyCar with ID '4' is a FamilyCar, you can do the following to fetch the entity into a FamilyCar instance:

FamilyCarEntity car = (FamilyCarEntity)CompanyCarEntity.FetchPolymorphic(null, 4, null);

As this method accepts a transaction, it can be handy in some cases to use this method over a constructor call. To keep things simple, you should first look at the constructor method:

FamilyCarEntity car = new FamilyCarEntity(4);

FetchPolymorphicUsingUC...

Another way to fetch an entity polymorphically is when it has a unique constraint and is in a hierarchy. You then can use the unique constraint's values to fetch an entity polymorphically similar to the FetchPolymorphic method for fetching an entity using the primary key. Say Employee has an unique constraint on 'Name'. To fetch an employee polymorphically, you can use the following code.

BoardMemberEntity b = (BoardMemberEntity)EmployeeEntity.FetchPolymorphicUsingUCName(null, "J.D. Rockefeller III", null);