The FwkLight blog

The lazy = “false” mapping

abutnaru — Wed, 28 Apr 2010 16:32:00 +0000

Using lazy = "false" mappings is a very bad practice, and overrides any possibility to use fetching strategies.

Even if at a certain point something seems to be necessary all the time and lazy = "false" might make sense, the application will evolve and a context will appear in which that thing will not be necessary – unfortunately you will load it even if you don’t want it, because of the mapping. The solution if you are in this situation and you want to solve it is to remove the lazy = "false" mapping and create fetching strategies, but the refactoring can be quite painful.

IT IS YOUR RESPONSABILITY NOT TO CREATE lazy="false" MAPPINGS.

Fetching strategies and complex hierarchies

abutnaru — Wed, 28 Apr 2010 16:27:18 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

Fetching strategies can be applied to aggregates with complex hierarchies, not only to the first level inside the aggregate.

In order to optimize the queries that will be run, each element (entity or list) from the main hierarchy which has a list specified in its internal hierarchy should have the parent field configured; this is because separated selects are generated for the lists, and joins need to be made to reach the initial filters; if the element does not know its parent, the select will bring much more information than it should.

In the ComplexHierarchy action of the FetchingStrategiesController, we first instruct NHibernate to use a certain fetching strategy when executing the load task:

Task<CustomerOrderSet5LoadTask>().ShouldUseFetchingStrategy<CustomerOrderSet5FetchingForFetchingStrategiesComplexHierarchy>();

and after that we execute the task:

var orderSet = _customerOrderSet5LoadTask.Execute(1);

Here is how the fetching strategy looks:

public class CustomerOrderSet5FetchingForFetchingStrategiesComplexHierarchy: IFetchingStrategy<CustomerOrderSet5>
{
    public void ApplyStrategyOn(IMultiCriteriaFetcher<CustomerOrderSet5> repository)
    {
        repository
            .InitFetchingHierarchy()
            .WhichAlsoContainsList(p => p.CustomerOrders, u => u.CustomerOrderSet5)
            .WhichAlsoContainsList(p => p.OrderDetails)
            .WhichAlsoContainsEntity(p => p.Product5)
            .BackTo<CustomerOrderSet5>()
            .WhichAlsoContainsEntity(p => p.Client5)
            .WhichAlsoContainsList(p => p.Addresses)
            .BackTo<CustomerOrderSet5>()
            .WhichAlsoContainsEntity(p => p.PaymentType5);
    }
}

This is all that is required to load the CustomerOrderSet with Id 1 together with its orders, each order with its order details, each order detail with its product, also with the client and its addresses, and also with the payment type.

You can see here:

.WhichAlsoContainsList(p => p.CustomerOrders, u => u.CustomerOrderSet5)

how we tell FwkLight in the second parameter about the parent field for the CustomerOrders list, in order to load the list contained in each CustomerOrder (the list of order details) efficiently.

Fetching strategies

abutnaru — Wed, 28 Apr 2010 16:15:19 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

Fetching strategies represent a way to tell NHibernate what you want to load inside an aggregate (or list of aggregates) before you load it.

You should use a fetching strategy whenever you need to load an aggregate with entities in it (or lists of entities in it), or lists of aggregates in which every element has entities in it (or lists of entities in it).

IT IS YOUR RESPONSABILITY TO USE FETCHING STRATEGIES WHENEVER YOU NEED TO LOAD AGGREGATES AND THEIR SUBENTITIES, WHEN WORKING WITH FWKLIGHT.

This mechanism provided by FwkLight offers you a way to completely define everything you want to load inside the aggregate, so you should never need to manually load something related to an aggregate after you already loaded the aggregate (doing so would make your implementation more complicated, and lower the stability of the code).

You create fetching strategies by writing classes which implement the IFetchingStrategy interface. The key to configuring a fetching strategy is the IMultiCriteriaFetcher interface, which offers a fluent interface (IListMultiCriteriaFetcher) through which you can instruct NHibernate on how to generate the NHibernate multicriteria for loading the aggregate (aggregates). When executed, the multicriteria will run a batch select on the database and load everything very efficiently, in one roundtrip.

In this example, the fetching strategy instructs FwkLight to load the CustomerOrder with its OrderDetails:

public class CustomerOrder1Fetching: IFetchingStrategy<CustomerOrder1>
{
    public void ApplyStrategyOn(IMultiCriteriaFetcher<CustomerOrder1> repository)
    {
        repository
            .InitFetchingHierarchy()
            .WhichAlsoContainsList(p => p.OrderDetails);
    }
}

The query has the CustomerOrder1Fetching strategy specified, so each time the query is executed it will load its list of orders according to this strategy:

public class AggregateListQuery3 : MultiCriteriaQuery<CustomerOrder1>
{
    private readonly CustomerOrder1Fetching _customerOrder1Fetching;
    private decimal _minPrice;

    public AggregateListQuery3(CustomerOrder1Fetching customerOrder1Fetching)
    {
        _customerOrder1Fetching = customerOrder1Fetching;
    }

    public IList<CustomerOrder1> Execute(ISession session, decimal minPrice)
    {
        _minPrice = minPrice;
        return Load(session);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<CustomerOrder1> criteria)
    {
        criteria.Where(p => p.OrderPrice).Gt(_minPrice);
    }

    protected override IFetchingStrategy<CustomerOrder1> FetchingStrategy
    {
        get
        {
            return _customerOrder1Fetching;
        }
    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<CustomerOrder1> criteria) { }

    protected override void Sort(IListMultiCriteriaFetcher<CustomerOrder1> criteria) { }
}

Active items and sorting

abutnaru — Wed, 28 Apr 2010 12:54:43 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

Each query implementation asks you (through abstract methods) how it should bring only the active items and how it should do the sorting.

IT IS YOUR RESPONSABILITY TO IMPLEMENT THESE METHODS WHEN NECCESARY, AND NOT JUST OVERRIDE THEM AND MOVE ON TO SOMETHING ELSE.

Sorting

Sorting is ussualy not critical, but it’s quite important from time to time.

Here are 2 queries which implement sorting by overriding the Sort method:

public class AggregateListQuery1: MultiCriteriaQuery<CustomerOrder1>
{
    private decimal _minPrice;

    public IList<CustomerOrder1> Execute(ISession session, decimal minPrice)
    {
        _minPrice = minPrice;
        return Load(session);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<CustomerOrder1> criteria)
    {
        criteria.Where(p => p.OrderPrice).Gt(_minPrice);
    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<CustomerOrder1> criteria){}

    protected override void Sort(IListMultiCriteriaFetcher<CustomerOrder1> criteria)
    {
        criteria.OrderAscBy(p => p.OrderPrice);
    }
}

public class BonusHistory2ListQuery : LinqQuery<BonusHistory2>
{
    private DateTime _startDate;
    private DateTime? _endDate;
    private Client2 _client;

    public IList<BonusHistory2> Execute(ISession session, DateTime startDate, DateTime? endDate, Client2 client)
    {
        _startDate = startDate;
        _endDate = endDate;
        _client = client;

        return Load(session);
    }

    protected override void GetMainQuery()
    {
        _queryable = from q in _queryable
                     where q.Year >= _startDate.Year
                           && q.Month >= _startDate.Month
                           && q.Client2 == _client
                     select q;

        if (_endDate != null)
        {
            _queryable = from q in _queryable
                         where q.Year <= _endDate.Value.Year
                               && q.Month <= _endDate.Value.Month
                         select q;
        }
    }

    public override void FilterOnlyActive() { }

    public override void Sort()
    {
        _queryable = (from q in _queryable
                      orderby q.Month descending
                                    orderby q.Year descending
                      select q);
    }
}

Active items

Fetching only active items is usually critical, when it applies.

Imagine that you want to be able to see all products in the admin area (so you can edit them, activate or deactivate them), but you only want your clients to see the active products. If you use the same query to load the products for both admin and client area, you have to tell your query when to include the inactive products and when not, otherwise your clients might have the unpleasant surprise of working with inactive products.

The decision of including the inactive items can be made at the UI / controller layer or at the application layer, depending on the requirements. The difference is that the application task which wraps the query will expect the parameter when executed by the controller, or make the decision itself without expecting a parameter.

In the SortingAndActiveItems action of the QueryController:

- we first load the list of active products by making the decision in the controller (the application task expects the parameter for including the inactive items or not)

var productList1 = _product2ListTask.Execute(false);

Product2ListTask is a wrapper for Product2Query, which also passes the decision from the controller to the query:

public class Product2ListTask: BaseListQueryTask<Product2>
{
    private readonly Product2Query _product2Query;
    private bool _includeInactive;

    public Product2ListTask(INHUnitOfWorkProvider uowProvider, Product2Query product2Query) : base(uowProvider)
    {
        _product2Query = product2Query;
    }

    public IList<Product2> Execute(bool includeInactive)
    {
        _includeInactive = includeInactive;
        ExecuteInternal();
        return Entity;
    }

    protected override IList<Product2> ExecuteQuery()
    {
        return _product2Query.Execute(UOW.Session, _includeInactive);
    }
}

The query implements a method to bring only the active items by overriding the FilterOnlyActive method, and offers 2 Execute entry points (one which expects the decision from outside, and one which defaults to excluding the inactive items):

public class Product2Query: MultiCriteriaQuery<Product2>
{
    public IList<Product2> Execute(ISession session, bool includeInactive)
    {
        return Load(session, includeInactive);
    }

    public IList<Product2> Execute(ISession session)
    {
        return Execute(session, false);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<Product2> criteria)
    {

    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<Product2> criteria)
    {
        criteria.Where(p => p.IsActive).Eq(true);
    }

    protected override void Sort(IListMultiCriteriaFetcher<Product2> criteria)
    {
        criteria.OrderAscBy(p => p.ProductName);
    }
}

Here is how the entity looks like:

public class Product2
{
    public virtual int Id { get; set; }
    public virtual string ProductName { get; set; }
    public virtual bool IsActive { get; set; }
}

- in the second example, we load the same list of active products by making the decision in the application layer (the application task always excludes inactive items when executing the query):

var productList2 = _clientProductListTask.Execute();

public class ClientProductListTask: BaseListQueryTask<Product2>
{
    private readonly Product2Query _product2Query;

    public ClientProductListTask(INHUnitOfWorkProvider uowProvider, Product2Query product2Query) : base(uowProvider)
    {
        _product2Query = product2Query;
    }

    public IList<Product2> Execute()
    {
        ExecuteInternal();
        return Entity;
    }

    protected override IList<Product2> ExecuteQuery()
    {
        return _product2Query.Execute(UOW.Session, false);
    }
}

This also applies to situations when you have a certain state which is equivalent to the item being disabled (for example, a Cancelled state), and the same query needs to load the list including / excluding items in that state.

- in the third example, we load only orders which are not cancelled:

var ordersNotCancelled = _customerOrder4ListTask.Execute(false);

The task is simply a wrapper for the query:

public class CustomerOrder4ListTask: BaseListQueryTask<CustomerOrder4>
{
    private readonly CustomerOrder4Query _customerOrder4Query;
    private bool _includeCancelled;

    public CustomerOrder4ListTask(INHUnitOfWorkProvider uowProvider, CustomerOrder4Query customerOrder4Query) : base(uowProvider)
    {
        _customerOrder4Query = customerOrder4Query;
    }

    public IList<CustomerOrder4> Execute(bool includeCancelled)
    {
        _includeCancelled = includeCancelled;
        ExecuteInternal();
        return Entity;
    }

    protected override IList<CustomerOrder4> ExecuteQuery()
    {
        return _customerOrder4Query.Execute(UOW.Session, _includeCancelled);
    }
}

The query implements a method to filter the Cancelled orders:

public class CustomerOrder4Query: MultiCriteriaQuery<CustomerOrder4>
{
    public IList<CustomerOrder4> Execute(ISession session, bool includeCancelled)
    {
        return Load(session, includeCancelled);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<CustomerOrder4> criteria)
    {

    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<CustomerOrder4> criteria)
    {
        criteria.Where(p => p.State).NotEq(CustomerOrderState.Cancelled);
    }

    protected override void Sort(IListMultiCriteriaFetcher<CustomerOrder4> criteria)
    {
        criteria.OrderDescBy(p => p.OrderPrice);
    }
}

And here are the entity and states enum:

public enum CustomerOrderState { InWork = 1, Sent = 2, Cancelled = 3, Accepted = 4}

public class CustomerOrder4
{
    public virtual int Id { get; set; }
    public virtual decimal OrderPrice { get; set; }
    public virtual CustomerOrderState State { get; set; }
}

Query types

abutnaru — Tue, 27 Apr 2010 13:52:57 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

There are 5 implementations of queries in FwkLight, and each time you should choose the appropriate one based on what you need by following this rule:

1. if you are using a stored procedure (you should do that very rarely), use a NamedQuery
2. if you are not using a stored procedure, try to use a Linq query
3. if 2 is not possible, try to use a MultiCriteria query
4. is 3 is not possible, try to use a Criteria query
5. if 4 is not possible, use a HQL query

HqlQuery

This is a query which can be configured with NHibernate’s HQL API.

It is quite flexible, but you should use it only if none of the others work because it has 2 big drawbacks: you will use strings to build the queries, and you don’t have good support for loading complex hierarchies.

When deciding to use it, you should also consider that this type of query cannot load complex aggregates efficiently and cannot use fetching strategies. If you need to load a list of aggregates in which every aggregate contains a complex hierarchy, your only good choice is MultiCriteriaQuery.

Example:

public class CalculatedPrimitiveQuery1 : HqlQuery<Client2, int>
{
    private Client2 _client;

    public decimal Execute(ISession session, Client2 client)
    {
        _client = client;
        return LoadUnique(session);
    }

    protected override string HQLForActiveItems
    {
        get
        {
            return @"select max(dl.DiscountPercentage) from DiscountLevel2 as dl
              where dl.DiscountPercentage <=
                 (select max(dl1.DiscountPercentage)
                        from DiscountLevel2 as dl1
                          where dl1.ClientTypeWithLimit = :ClientType
                          or
                          not exists (select dl1.DiscountPercentage from DiscountLevel2 as dl1
                            where dl1.ClientTypeWithLimit = :ClientType)
                )";
        }
    }

    protected override string HQLForAllItems
    {
        get { throw new NotImplementedException(); }
    }

    public override void SetParameters(IQuery query)
    {
        query.SetInt32("ClientType", (int)_client.ClientType);
    }

    protected override string Sorting
    {
        get
        {
            return "";
        }
    }
}

CriteriaQuery

This is a query which can be configured with NHibernate’s Criteria API.

It still uses some strings, but you will hardcode less information than with a HQL query.

This type of query is the best choice for paged UI lists.

Example:

public class CalculatedPrimitiveQuery2 : CriteriaQuery<CustomerOrder2, int>
{
  private Client2 _client;

  public override void GetMainCriteria(ICriteria criteria)
  {
    criteria.Add(Restrictions.Eq("IsLaunched", true))
      .Add(Restrictions.Eq("Client2", _client))
      .SetProjection(Projections.Id());
  }

  public bool Execute(ISession session, Client2 client)
  {
    _client = client;
    return Load(session).Count > 0;
  }

  public override void FilterOnlyActive(ICriteria criteria){}

  public override void Sort(ICriteria criteria){}
}

MultiCriteriaQuery

This is FwkLight’s implementation for a query, which uses a fluent interface (IListMultiCriteriaFetcher) to generate an NHibernate multicriteria.

To configure the fetching strategy of the query, you override the FetchingStrategy property.

public class AggregateListQuery3 : MultiCriteriaQuery<CustomerOrder1>
{
    private readonly CustomerOrder1Fetching _customerOrder1Fetching;
    private decimal _minPrice;

    public AggregateListQuery3(CustomerOrder1Fetching customerOrder1Fetching)
    {
        _customerOrder1Fetching = customerOrder1Fetching;
    }

    public IList<CustomerOrder1> Execute(ISession session, decimal minPrice)
    {
        _minPrice = minPrice;
        return Load(session);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<CustomerOrder1> criteria)
    {
        criteria.Where(p => p.OrderPrice).Gt(_minPrice);
    }

    protected override IFetchingStrategy<CustomerOrder1> FetchingStrategy
    {
        get
        {
            return _customerOrder1Fetching;
        }
    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<CustomerOrder1> criteria) { }

    protected override void Sort(IListMultiCriteriaFetcher<CustomerOrder1> criteria) { }
}

Here is how the fetching strategy looks like:

public class CustomerOrder1Fetching: IFetchingStrategy<CustomerOrder1>
{
    public void ApplyStrategyOn(IMultiCriteriaFetcher<CustomerOrder1> repository)
    {
        repository
            .InitFetchingHierarchy()
            .WhichAlsoContainsList(p => p.OrderDetails);
    }
}

LinqQuery

This is a query which can be configured through Linq means, and uses NHibernate2Linq. This is the best way to define queries, will be upgraded and maintained by the community, but it is very new, not yet mature, and has many limitations. You can use it only in very simple scenarios.

public class BonusHistory2ListQuery : LinqQuery<BonusHistory2>
{
    private DateTime _startDate;
    private DateTime? _endDate;
    private Client2 _client;

    public IList<BonusHistory2> Execute(ISession session, DateTime startDate, DateTime? endDate, Client2 client)
    {
        _startDate = startDate;
        _endDate = endDate;
        _client = client;

        return Load(session);
    }

    protected override void GetMainQuery()
    {
        _queryable = from q in _queryable
                     where q.Year >= _startDate.Year
                           && q.Month >= _startDate.Month
                           && q.Client2 == _client
                     select q;

        if (_endDate != null)
        {
            _queryable = from q in _queryable
                         where q.Year <= _endDate.Value.Year
                               && q.Month <= _endDate.Value.Month
                         select q;
        }
    }

    public override void FilterOnlyActive() { }

    public override void Sort()
    {
        _queryable = (from q in _queryable
                      orderby q.Month descending
                                    orderby q.Year descending
                      select q);
    }
}

AllItemsQuery

This is a Linq query which loads all the entities of a certain type. It is a shortcut to load all the information from small database tables.

NamedQuery

This is a query which works with a stored procedure.

public class BonusStatisticsQuery : NamedQuery<BonusStatistic>
{
    private Client2 _client;

    public BonusStatistic Execute(ISession session, Client2 client)
    {
        _client = client;
        return UniqueResult(session);
    }

    protected override void SetParameters(IQuery query)
    {
        query.SetParameter("clientId", _client.Id);
    }

    protected override string QueryName
    {
        get
        {
            return "ClientBonusStatistics";
        }
    }
}

The BonusStatistic entity looks like this:

public class BonusStatistic
{
    public virtual int Id { get; set; }
    public virtual decimal TotalBonusGained { get; set; }
}

The entity mapping also maps the stored procedure:

xml version="1.0" encoding="utf-8" ?>

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" schema="dbo" assembly="FwkLightDemo.Domain"  namespace="FwkLightDemo.Domain.Entities">
  <class name="BonusStatistic" table="BonusStatistic">
        <id name="Id" column="Id" type="Int32">
            <generator class="assigned">generator>
        id>

        <property name="TotalBonusGained"/>

  class>

    <sql-query name="ClientBonusStatistics">
        <return class="BonusStatistic" />
        exec dbo.[FwkLightDemo_ClientBonusStatistics] :clientId
    sql-query>

hibernate-mapping>

And the stored procedure expects the clientId parameter:

CREATE PROCEDURE [dbo].[FwkLightDemo_ClientBonusStatistics] 

@clientId int

AS
BEGIN

    select
    sum(BonusGained) as TotalBonusGained,
    convert(int, rand()* 100000) as Id
    from BonusHistory2
    where Client2Id = @clientId

END

Executing and using queries

abutnaru — Tue, 27 Apr 2010 13:19:12 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

You should Execute queries only in Application Tasks, and only in these 2 places:

in the LoadAdditionalInitialData method of an Application Task

Example:

public class CalculatedPrimitiveTask2 : BaseApplicationTask<decimal>
{
  private readonly DiscountLevel2ListTask _discountLevel2ListTask;
  private readonly MaxDiscountPercentage _maxDiscountPercentage;
  private Client2 _client;
  private IList<DiscountLevel2> _discountLevel2List;

  public CalculatedPrimitiveTask2(INHUnitOfWorkProvider uowProvider, DiscountLevel2ListTask discountLevel2ListTask, MaxDiscountPercentage maxDiscountPercentage) : base(uowProvider)
  {
    _discountLevel2ListTask = discountLevel2ListTask;
    _maxDiscountPercentage = maxDiscountPercentage;
  }

  public decimal Execute(Client2 client)
  {
    _client = client;
    ExecuteInternal();
    return Entity;
  }

  protected override void LoadAdditionalInitialData()
  {
    _discountLevel2List = _discountLevel2ListTask.Execute();
  }

  protected override void ExecuteBusinessLogic()
  {
    Entity = _client.CalculateThe(_maxDiscountPercentage, _discountLevel2List);
  }
}

DiscountLevel2ListTask is an AllItemsTask, which is a wrapper for an AllItemsQuery (which loads all the entities of a certain type):

public class DiscountLevel2ListTask: AllItemsTask<DiscountLevel2>
{
  public DiscountLevel2ListTask(INHUnitOfWorkProvider uowProvider, AllItemsQuery<DiscountLevel2> allItemsQuery) : base(uowProvider, allItemsQuery)
  {
  }
}

in a Query Task

Example:

The AggregateListQuery1 is executed in the ExecuteQuery method of the QueryTask:

public class AggregateListTask1 : BaseListQueryTask<CustomerOrder1>
{
    private readonly AggregateListQuery1 _aggregateListQuery1;
    private decimal _minPrice;

    public AggregateListTask1(INHUnitOfWorkProvider uowProvider, AggregateListQuery1 aggregateListQuery1) : base(uowProvider)
    {
        _aggregateListQuery1 = aggregateListQuery1;
    }

    public IList<CustomerOrder1> Execute(decimal minPrice)
    {
        _minPrice = minPrice;
        ExecuteInternal();
        return Entity;
    }

    protected override IList<CustomerOrder1> ExecuteQuery()
    {
        return _aggregateListQuery1.Execute(UOW.Session, _minPrice);
    }
}

public class AggregateListQuery1: MultiCriteriaQuery<CustomerOrder1>
{
    private decimal _minPrice;

    public IList<CustomerOrder1> Execute(ISession session, decimal minPrice)
    {
        _minPrice = minPrice;
        return Load(session);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<CustomerOrder1> criteria)
    {
        criteria.Where(p => p.OrderPrice).Gt(_minPrice);
    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<CustomerOrder1> criteria){}

    protected override void Sort(IListMultiCriteriaFetcher<CustomerOrder1> criteria)
    {
        criteria.OrderAscBy(p => p.OrderPrice);
    }
}

IT IS YOUR RESPONSABILITY TO NOT EXECUTE QUERIES ANYWHERE ELSE WHEN WORKING WITH FWKLIGHT.

The Query uses an Execute convention, and one of the parameters of the Execute method should be the current NHibernate Session (the Session property of the current UnitOfWork, which is offered by the Application Task through the UOW property – example above).

Queries and calculated primitives

abutnaru — Tue, 27 Apr 2010 10:10:53 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

By primitive we are referring to a boolean, an int, a decimal, etc. You sometimes need to apply a formula to calculate a primitive, and you have the option of doing it in the domain or in the database.

To let the database apply the formula and return the result, you need to create a query which makes the necessary database call. Here is an example of a query which calculates the maximum discount percentage that a client can receive, based on a list of discount levels and the client type. The query uses HQL (Hibernate Query Language) to apply the formula in the HQLForActiveItems method:

public class CalculatedPrimitiveQuery1 : HqlQuery<Client2, int>
{
    private Client2 _client;

    public decimal Execute(ISession session, Client2 client)
    {
        _client = client;
        return LoadUnique(session);
    }

    protected override string HQLForActiveItems
    {
        get
        {
            return @"select max(dl.DiscountPercentage) from DiscountLevel2 as dl
              where dl.DiscountPercentage <=
                 (select max(dl1.DiscountPercentage)
                        from DiscountLevel2 as dl1
                          where dl1.ClientTypeWithLimit = :ClientType
                          or
                          not exists (select dl1.DiscountPercentage from DiscountLevel2 as dl1
                            where dl1.ClientTypeWithLimit = :ClientType)
                )";
        }
    }

    protected override string HQLForAllItems
    {
        get { throw new NotImplementedException(); }
    }

    public override void SetParameters(IQuery query)
    {
        query.SetInt32("ClientType", (int)_client.ClientType);
    }

    protected override string Sorting
    {
        get
        {
            return "";
        }
    }
}

Most of the times when you seem to need a query with this purpose, the calculation should be done inside one of the existing aggregates or one that you did not identify yet. The fact that the aggregate is not used is already a problem, and isolating the calculation in a query adds more to it.

When you isolate a calculation inside a query, you make a decision that the calculation will always be needed directly from the database and you give it a form that is database-related (as you can see in the example above); in a way, you put that formula in the database instead of the domain and you lose the flexibility that the domain offers. As soon as the calculation will be needed inside the domain, you will face a duplication of logic (the calculation will be written once more, this time in the domain) or a painful refactor (to extract the calculation from the query, into a form that both the query and domain can use).

Plus, you are giving the query 2 responsibilities: the classical responsibility of loading something from the database, plus the responsibility of being the keeper of that business formula; both these responsibilities are heavy, so it’s best to not mix them.

It’s good to avoid these problems altogether, and use queries only for loading lists of aggregates as much as you can.

In conclusion, when you seem to need a query which loads a primitive from the database, use this simple guideline:

if the formula must be applied over a big list of entities (>1000) or a list which you expect to grow very fast (today it will be applied on 100 database entries, in one month it will be applied on 1000, and so on), use a query to apply the formula
otherwise, apply the formula in the domain
- what makes sense to be in the aggregate – load with the aggregate
- what does not make sense to be in the aggregate – load independently
- create an aggregate extension which uses the aggregate and the other dependencies as parameters, to apply the formula and calculate the primitive

In the CalculatedPrimitives action of the QueryController:

- we first load the client:

var client = _client2LoadTask.Execute(1);

- after that, we calculate the maximum discount percentage that the client can receive using the above query:

var maxDiscountPercentageBad = _calculatedPrimitiveTask1.Execute(client);

CalculatedPrimitiveTask1 is simply a wrapper for the CalculatedPrimitiveQuery1:

public class CalculatedPrimitiveTask1 : BaseQueryTask<Client2, decimal>
{
  private readonly CalculatedPrimitiveQuery1 _calculatedPrimitiveQuery1;
  private Client2 _client;

  public CalculatedPrimitiveTask1(INHUnitOfWorkProvider uowProvider, CalculatedPrimitiveQuery1 calculatedPrimitiveQuery1) : base(uowProvider)
    {
      _calculatedPrimitiveQuery1 = calculatedPrimitiveQuery1;
    }

  public decimal Execute(Client2 client)
    {
    _client = client;
        ExecuteInternal();
        return Entity;
    }

  protected override decimal ExecuteQuery()
    {
    return _calculatedPrimitiveQuery1.Execute(UOW.Session, _client);
    }
}

As we have seen in the CalculatedPrimitiveQuery1 query, we will end up with a complicated HQL formula which will surely bring problems in the long run.

- in the second example, we make the same calculation but this time in the domain:

var maxDiscountPercentageGood = _calculatedPrimitiveTask2.Execute(client);

This solution uses the guideline that we presented earlier, because the task loads the list of discount levels separately in the LoadAdditionalInitialData method:

public class CalculatedPrimitiveTask2 : BaseApplicationTask<decimal>
{
  private readonly DiscountLevel2ListTask _discountLevel2ListTask;
  private readonly MaxDiscountPercentage _maxDiscountPercentage;
  private Client2 _client;
  private IList<DiscountLevel2> _discountLevel2List;

  public CalculatedPrimitiveTask2(INHUnitOfWorkProvider uowProvider, DiscountLevel2ListTask discountLevel2ListTask, MaxDiscountPercentage maxDiscountPercentage) : base(uowProvider)
  {
    _discountLevel2ListTask = discountLevel2ListTask;
    _maxDiscountPercentage = maxDiscountPercentage;
  }

  public decimal Execute(Client2 client)
  {
    _client = client;
    ExecuteInternal();
    return Entity;
  }

  protected override void LoadAdditionalInitialData()
  {
    _discountLevel2List = _discountLevel2ListTask.Execute();
  }

  protected override void ExecuteBusinessLogic()
  {
    Entity = _client.CalculateThe(_maxDiscountPercentage, _discountLevel2List);
  }
}

and the formula is encapsulated in an entity extension (a Calculator) which is executed in the ExecuteBusinessLogic method:

public class MaxDiscountPercentage : ICalculator<decimal, Client2, IList<DiscountLevel2>>
{
  public decimal Calculate(Client2 client, IList<DiscountLevel2> discountLevels)
  {
    var maxLevel = discountLevels.FirstOrDefault(p => p.ClientTypeWithLimit == client.ClientType);
    if (maxLevel != null)
      return maxLevel.DiscountPercentage;

    return discountLevels.Max(p => p.DiscountPercentage);
  }
}

With this solution, everything remains in the domain, nicely encapsulated, and we don’t lose any flexibility.

Aggregate lists vs Queries

abutnaru — Mon, 26 Apr 2010 10:54:06 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

Loading lists of aggregates is not the same with loading a list inside an aggregate.

For example, if CustomerOrder is an aggregate and the business of the application suggests that it should contain a list of OrderDetails, you might load a list of CustomerOrders with a query at some point, but you should not use a query to load the list of OrderDetails for a CustomerOrder. Instead, to obtain the list of OrderDetails for a CustomerOrder you should load the CustomerOrder with a repository (or load a list of CustomerOrders with a query), and ask the CustomerOrder for its OrderDetails.

Here is how these entities and their mappings look like:

public class OrderDetail1
{
    public virtual int Id { get; set; }
    public virtual decimal OrderDetailPrice { get; set; }

    public virtual CustomerOrder1 CustomerOrder1 { get; set; }
}

xml version="1.0" encoding="utf-8" ?>

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" schema="dbo" assembly="FwkLightDemo.Domain"  namespace="FwkLightDemo.Domain.Entities">
  <class name="OrderDetail1" table="OrderDetail1">
    <id name="Id" type="Int32" column="OrderDetail1Id" >
      <generator class="identity" />
    id>

        <many-to-one name="CustomerOrder1" column="CustomerOrder1Id" class="CustomerOrder1" not-null="true" />

        <property name="OrderDetailPrice"/>

  class>
hibernate-mapping>

public class CustomerOrder1
{
    public virtual int Id { get; set; }
    public virtual decimal OrderPrice { get; set; }
    public virtual IList<OrderDetail1> OrderDetails { get; set; }
}

xml version="1.0" encoding="utf-8" ?>

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" schema="dbo" assembly="FwkLightDemo.Domain"  namespace="FwkLightDemo.Domain.Entities">
  <class name="CustomerOrder1" table="CustomerOrder1">
    <id name="Id" type="Int32" column="CustomerOrder1Id" >
      <generator class="identity" />
    id>

        <property name="OrderPrice"/>

        <bag name="OrderDetails" inverse="true">
            <key column="CustomerOrder1Id" />
            <one-to-many class="OrderDetail1" />
        bag>

  class>
hibernate-mapping>

In the QueryController we have the AggregateLists action, where:

- we first load a list of CustomerOrders, select the one for which we need to retrieve the OrderDetails and ask it for its OrderDetails:

var customerOrderList = _aggregateListTask1.Execute(2);
var orderForWhichWeRetrieveDetails = customerOrderList.FirstOrDefault(p => p.Id == 3);

var orderDetailListGood = orderForWhichWeRetrieveDetails.OrderDetails;

This is the efficient way to access the list of OrderDetails for a CustomerOrder, and the efficient way to access a list of subentities inside an aggregate.

- after that, we obtain the same list of OrderDetails by executing a query specialized in retrieving the OrderDetails for a CustomerOrder:

var orderDetailListBad = _aggregateListTask2.Execute(orderForWhichWeRetrieveDetails);

The AggregateListTask2 QueryTask is simply a wrapper for AggregateListQuery2:

public class AggregateListQuery2: MultiCriteriaQuery<OrderDetail1>
{
    private CustomerOrder1 _order;

    public IList<OrderDetail1> Execute(ISession session, CustomerOrder1 order)
    {
        _order = order;
        return Load(session);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<OrderDetail1> criteria)
    {
        criteria.Where(p => p.CustomerOrder1).Eq(_order);
    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<OrderDetail1> criteria) { }

    protected override void Sort(IListMultiCriteriaFetcher<OrderDetail1> criteria) { }
}

public class AggregateListTask2 : BaseListQueryTask<OrderDetail1>
{
    private readonly AggregateListQuery2 _aggregateListQuery2;
    private CustomerOrder1 _order;

    public AggregateListTask2(INHUnitOfWorkProvider uowProvider, AggregateListQuery2 aggregateListQuery2) : base(uowProvider)
    {
        _aggregateListQuery2 = aggregateListQuery2;
    }

    public IList<OrderDetail1> Execute(CustomerOrder1 order)
    {
        _order = order;
        ExecuteInternal();
        return Entity;
    }

    protected override IList<OrderDetail1> ExecuteQuery()
    {
        return _aggregateListQuery2.Execute(UOW.Session, _order);
    }
}

This is the complicated way to access the list of OrderDetails for a CustomerOrder, and the complicated way to access a list of subentities inside an aggregate. By using this method you work more (you create at least 2 more classes), only to obtain code that is harder to control and maintain.

You should use the efficient method as often as you can, but there are a few things to consider.

When to favor loading lists inside aggregates over dedicated queries

We first have to make an observation: for one context an entity must be considered an aggregate (it cannot be loaded inside any of the entities which are loaded in that context), and for another context the same entity can be considered a subentity (it can be loaded inside one of the other entities which are loaded in that context). This subtle difference is dictated by the business of the application and by each functionality / context that we are implementing, and making good use of it is essential.

As an example, let’s consider that a CustomerOrderSet can contain 1-100 CustomerOrders. If we need to show the list with all CustomerOrders, then we are only talking about the orders so there is no aggregate inside which we could load them – CustomerOrder is the aggregate. If we need to show the list of CustomerOrders for a CustomerOrderSet, then we have a context for the CustomerOrders, the CustomerOrderSet – CustomerOrderSet is the aggregate, and we can consider CustomerOrder its subentity.

Here is how we use this observation:

- when the entity must be considered an aggregate, we always load the single instance with a repository and the list with a query

- when the entity can be considered a subentity, the simplified rule is: whenever you can load the list inside an aggregate without too much pain, do it

Here is how the detailed rule looks:

if you are implementing a list with a pager and / or filters, you should load its contents with a query (no aggregate should take responsibility for filtering / paging through one of its lists); you should also consider using a linear entity (which is more appropriate for displaying lists) instead of a normal entity, but that’s another story
if you need to load a big list of entities (>1000) or a list which you expect to grow very fast, you should use a query (such a list should be cached, and if displayed in the UI it should be filtered or paged – none of these are responsibilities for an aggregate; because of its size, such a list should never be included inside an aggregate because it has the potential to create performance bottlenecks – loading it with a dedicated query isolates it and reduces the risks)
if the aggregate inside which you can load the subentities must be loaded for the current context / page, you should load the list inside the aggregate
otherwise, you should use a query

Although there is only one case in which you should load the list inside the aggregate, it’s the one that happens most.

As an example, in the ListsInsideAggregatesOverQueries action inside the QueryController:

- we are first loading a list with all the CustomerOrders by using an AllItemsTask (which uses a query for loading all entities of a certain type):

var ordersWhenAggregateOk = _customerOrder3ListTask.Execute();

Here is how the entity and mapping looks like:

public class CustomerOrder3
{
  public virtual int Id { get; set; }
    public virtual decimal OrderPrice { get; set; }
    public virtual CustomerOrderSet3 CustomerOrderSet3 { get; set; }
}

xml version="1.0" encoding="utf-8" ?>

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" schema="dbo" assembly="FwkLightDemo.Domain"  namespace="FwkLightDemo.Domain.Entities">
  <class name="CustomerOrder3" table="CustomerOrder3">
    <id name="Id" type="Int32" column="CustomerOrder3Id" >
      <generator class="identity" />
    id>

        <property name="OrderPrice"/>

        <many-to-one name="CustomerOrderSet3" column="CustomerOrderSet3Id" class="CustomerOrderSet3" not-null="true" />

  class>
hibernate-mapping>

This is a case in which CustomerOrder is the aggregate, so it’s ok to load it separately with its own query.

- after that, we load a CustomerOrderSet with a LoadTask, and its CustomerOrders separately with a QueryTask:

var customerOrderSet = _customerOrderSet3LoadTask.Execute(1);
var ordersWhenNotAggregateBad = _customerOrder3ListTask2.Execute(customerOrderSet);

Here is the CustomerOrderSet entity looks like:

public class CustomerOrderSet3
{
    public virtual int Id { get; set; }
    public virtual decimal OrderSetPrice { get; set; }
    public virtual IList<CustomerOrder3> CustomerOrders { get; set; }
}

xml version="1.0" encoding="utf-8" ?>

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" schema="dbo" assembly="FwkLightDemo.Domain"  namespace="FwkLightDemo.Domain.Entities">
  <class name="CustomerOrderSet3" table="CustomerOrderSet3">
    <id name="Id" type="Int32" column="CustomerOrderSet3Id" >
      <generator class="identity" />
    id>

        <property name="OrderSetPrice"/>

        <bag name="CustomerOrders" inverse="true">
            <key column="CustomerOrderSet3Id" />
            <one-to-many class="CustomerOrder3" />
        bag>

  class>
hibernate-mapping>

CustomerOrderSet3LoadTask is a simple LoadTask:

public class CustomerOrderSet3LoadTask : BaseLoadTask<CustomerOrderSet3>
{
    private int _id;

    public CustomerOrderSet3LoadTask(IBaseRepo<CustomerOrderSet3> repository, INHUnitOfWorkProvider uowProvider)
        : base(repository, uowProvider)
    {
    }

    public CustomerOrderSet3 Execute(int id)
    {
        _id = id;
        ExecuteInternal();
        return Entity;
    }

    protected override void ConfigureFilters()
    {
        Fetcher.Where(p => p.Id).Eq(_id);
    }
}

CustomerOrder3Query2 is a query which loads the orders for an orderSet:

public class CustomerOrder3Query2: MultiCriteriaQuery<CustomerOrder3>
{
    private CustomerOrderSet3 _customerOrderSet3;

    public IList<CustomerOrder3> Execute(ISession session, CustomerOrderSet3 customerOrderSet3)
    {
        _customerOrderSet3 = customerOrderSet3;
        return Load(session);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<CustomerOrder3> criteria)
    {
        criteria.Where(p => p.CustomerOrderSet3).Eq(_customerOrderSet3);
    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<CustomerOrder3> criteria){}

    protected override void Sort(IListMultiCriteriaFetcher<CustomerOrder3> criteria){}
}

and the CustomerOrder3ListTask2 is a wrapper for it:

public class CustomerOrder3ListTask2: BaseListQueryTask<CustomerOrder3>
{
    private readonly CustomerOrder3Query2 _customerOrder3Query;
    private CustomerOrderSet3 _customerOrderSet3;

    public CustomerOrder3ListTask2(INHUnitOfWorkProvider uowProvider, CustomerOrder3Query2 customerOrder3Query) : base(uowProvider)
    {
        _customerOrder3Query = customerOrder3Query;
    }

    public IList<CustomerOrder3> Execute(CustomerOrderSet3 customerOrderSet3)
    {
        _customerOrderSet3 = customerOrderSet3;
        ExecuteInternal();
        return Entity;
    }

    protected override IList<CustomerOrder3> ExecuteQuery()
    {
        return _customerOrder3Query.Execute(UOW.Session, _customerOrderSet3);
    }
}

This is a case in which CustomerOrder can be considered a subentity (because we have an aggregate inside which we can load it – the CustomerOrderSet). We are not showing a list with a pager or filters, it’s not a big list (max 100) and it does not grow in time, so it’s not ok to load it separately with its own query like we did. Instead, we should load it together with the CustomerOrderSet aggregate.

- next, we obtain the same list of CustomerOrders directly from the CustomerOrderSet:

var ordersWhenNotAggregateGood = customerOrderSet.CustomerOrders;

Considering the conditions that we just described, this is the right approach.

Queries

abutnaru — Mon, 26 Apr 2010 10:24:39 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

The Query is the interface through which you will load lists of aggregates.

Whenever you need to load a list of aggregates from the database, you should think of a query.

Whenever you need to load one aggregate based on certain filters / rules, you should not use a query. By convention, the query is for loading lists of aggregates. To load one aggregate, you should always use a LoadTask (which will automatically use a repository).

Queries are services which live somewhere between the database and the domain. Together with the repositories, they form a bridge between your application and the database. Using them for more than just loading lists of aggregates can lead to instable or low quality code, because you are taking business logic away from the domain.

Here is an example of a Query which loads all entities with IDs in the given list:

public class SomeEntityListQuery: MultiCriteriaQuery<SomeEntity>
{
    private IList<int> _ids;

    public IList<SomeEntity> Execute(ISession session, IList<int> ids)
    {
        _ids = ids;
        return Load(session);
    }

    protected override void ApplyMainFilters(IListMultiCriteriaFetcher<SomeEntity> criteria)
    {
        criteria.Where(p => p.Id).In(_ids);
    }

    protected override void FilterOnlyActive(IListMultiCriteriaFetcher<SomeEntity> criteria){}

    protected override void Sort(IListMultiCriteriaFetcher<SomeEntity> criteria){}
}

Repository

abutnaru — Sat, 24 Apr 2010 11:07:05 +0000

ALL THE EXAMPLES FROM THIS POST ARE EXTRACTED FROM THE FWKLIGHT DEMO. TO FIND OUT HOW TO GET STARTED WITH THE DEMO, READ THIS POST.

The Repository is the interface through which FwkLight manages the database related tasks for one aggregate (save, load, etc).

It works only with individual aggregates, not with lists of aggregates. When you need to load a list of aggregates, you should always use a Query (instead of a Repository).

When saving aggregates, it automatically uses the current UnitOfWork (you don’t have to manage that manually).

The repository uses an IMultiCriteriaFetcher (which can be accessed through the MultiCriteriaFetcher property) to do most of its work.

It is automatically instantiated in any BaseLoadTask or BaseSaveTask service, and you don’t need to use it directly. You will only use the IMultiCriteriaFetcher that it offers, so you can configure the necessary filters.

In the following example, the LoadTask configures its internal Repository by overriding the ConfigureFilters method:

public class SomeEntityLoadTask: BaseLoadTask<SomeEntity>
{
    private string _filter;

    public SomeEntityLoadTask(IBaseRepo<SomeEntity> repository, INHUnitOfWorkProvider uowProvider) : base(repository, uowProvider)
    {
    }

    public SomeEntity Execute(string filter)
    {
        _filter = filter;
        ExecuteInternal();
        return Entity;
    }

    protected override void ConfigureFilters()
    {
        Fetcher.Where(p => p.SomeEntityContent).Eq(_filter);
    }
}