How to use Blizzard

(To know more about Architecture please visit Blizzard Architecture)


Using Blizzard, you need to consider the followings:

Preparation


1 - Map your objects to the tables in the database

Blizzard is best suited for use in desktop applications without concurrent users. Therefore it is very simple to use. you need to use POCO objects. The best practice is to use one POCO object for every table you have in database (one to one mapping). Using Blizzard, typically you will start with mapping the objects (classes) to their corresponding tables. The mapping of an object will be done through attributes used in the class. The following attributes can be used to attach the mapping information to a class:

(Note: In this document, the terms: POCO objects, objects and classes are used interchangeably and basically refer to the same thing: a simple class which represents a data object. See Employee class below)

Mapping Example

In this example, we think of an application with four business objects: Employee, Customer, Department and Project. We are going to study the Employee object relationships with other three business objects. In short, the logic of relationships are as follows:


   [Mapper(Table = "Employees")]
    public class Employee : IDataObject
    {
        [Mapper(Field = "ID", IsIdentityColumn = true)]
        public int Id { get; set; }

        [Mapper(Field = "Name")]
        public virtual string Name { get; set; }

        public virtual BList<Customer> AssignedCustomers{get; set; }  // A one to many relationship (Employee as a parent)

        [Mapper(Field = "DepartmentId", Composition = false)]
        public virtual Department Department{get; set; } // A one to many relationship (Employee as a child)

        [Mapper(JoinTable = "Project_Employee", MyIdField = "EmployeeId")] //A many to many relationship
        public virtual BList<Project> Projects {get; set; }
     }


As you see above:

Alternative to Attribute Mapping

To map objects to tables, you are not limited to use the attribute mapping as described above. Basically you can do the mapping anyway you like as long as you implement the interface Blizzard.Mapper.IMapper. This is possible because the mapping structure is according to the strategy pattern:

IMapper.png

In the above diagram, the Client class is actually a class in your application who is about to use the Blizzard (more accurately: Blizzard.Container.BlizzardManager). The BlizzardManager is the most important class you need to instantiate in your Client class before you can use Blizzard. It is in your Client class that you determine which implementation of IMapper is going to be used by BlizzardManager, that’s why you have dependency lines in the diagram to the IMapper implementation. This is how it looks like in code:

AttrMapper mapper = new AttrMapper();
BlizzardManager manager = new BlizzardManager(mapper); // this constructor still needs another argument, please see below.



2 - Create a BlizzardManager Instance

To create an instance of a BlizzardManager you need one more thing. Very similar to passing a mapper object to the BlizzardManager constructor, you also need to pass an Blizzard.DAL.IDAO object to its constructor, that means that the code above is not very accurate (the BlizzardManager constructor should have two arguments).

IDAO dao = new SqlClientPlugin(ConnectionString);
AttrMapper mapper = new AttrMapper();

BlizzardManager manager = new BlizzardManager(dao, mapper);
Almost the same story about IDAO as we had with IMapper. It is a strategy pattern thing. The idea is the separation of Blizzard from certain database (certain sql syntax). The sql syntax is encapsulated in the implementation of IDAO, in the example above we used the SqlClientPlugin which is good for MS Sql Server. There are two other implementations available: ODBCPlugin and OledbPlugin. You can also add your own implementation. So Imagine you want to use MySql database, this is the place to do it.


Using Blizzard

Once your BlizzardManager object is created, this is how you can use it:

using Blizzard.Container;
using Blizzard.Contracts;


//Creating an object
Employee  employee= manager.CreateNewObject<Employee>();

//Persisting object(s)
manager.Update();

//Loading back one object
 Employee loadedEmployee = manager.Load<Employee>(employeeId);

//Loading back a list of objects
BList<Employee> employees = manager.Load<Employee>("Where Clause");

//Mark for deletion
manager.MarkForDeletion(employee);


Also it is important to use Blizzard.Contracts.BList<T> instead of List<T> or any other list. This is because when using BList, the list knows who the holder of the list is. And that is very important to support the relation awareness which exists in Blizzard. So imagine you are going to create a list of objects (children) first and then you want to assign it to a certain parent. This is how you are going to do it. (Assuming that Type A has a parent to child relationship with type B)


BList<B> listOfBees = new BList<B>(null);
            
B b1 = manager.CreateNewObject<B>();
B b2 = manager.CreateNewObject<B>();

listOfBees.Add(b1);
listOfBees.Add(b2);

//Now we are going to assign the listOfBees created above to the list of children (Bees) of an object of Type A (a)
//after assignement, the a.Bees list knows that it is related to a. this will be done inside the Blizzard
a.Bees = listOfBees;