How to use Blizzard

(To know more about Architecture please visit Blizzard Architecture)

Using Blizzard, you need to consider the followings:

All data types should implement Blizzard.Contracts.IDataObject interface. This is a very simple interface. All it does is to enforce the implementing class to have a property called “Id”.
All data types should be public
All data properties Should be public
All data properties (except for Identity Field property) should be virtual
All relations should be bidirectional. That means when a parent has list of children. The child type also need to have a property pointing to the parent object.

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)

Table (string - Represents the table name which a class is mapped to)
Field (string - Represents the field name which a property is mapped to)
IsIdentityColumn (bool - indicates that a field is mapped to an Identity field in database)
JoinTable (string - Represents a join table in a many to many relationship)
Composition (bool - Indicated whether a one to many relationship is a composition one)
MyIdField (string - Represents the related field for a property in the join table in a many to many relationship)

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:

An employee has a name.
An employee has a list of Customers who are assigned to him/her.
An employee can belong only to one department.
An employee can be involved in more than one project.


   [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:

The Employee class is mapped to the "Employees" table in the database.
The Id property is mapped to the "ID" field in the "Employees" table. Also "ID" field is an Identity field.
The Name property is mapped to the field: "Name".
The one to many relationship should be mapped in the child object (in this case: Customer class) that’s why we don’t have any mapping information for the property AssignedClients (for an example see how it is done with the Department property).
Persistence of a one to many relationships requires a parent id field in the child table in database. that’s why the mapping information for Department contains the name of the id field: "DepartmentId" which acts as a foreign key to the "Departments" table from the "Employees" table.
A many to many relationship requires mapping information on both sides of the relationship. the mapping information contains the join table name: "Project_Employee" and the corresponding field regarding this side of relationship (Employee side): "EmployeeId".

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:

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;