An Example of using NHibernate with .

NET

Gemunu R. Wickremasinghe

Change Log Version 0.5 1.0 Date 16 Aug 2005 th 17 Aug 2005
th

Initials GW GW

Remarks Draft Added introduction section (as suggested by CM). Expanded n-Tier Architecture to include Data Access Layer. Included Notes under sections 2.1.4.1.2 and 2.1.4.1.4 to suggest alternate approaches to replace XML mapping documents General fresh up Addressing review concerns Added whitepaper content to introduction Finishing touch

1.5 1.6 1.7 1.8

18 Aug 2005 th 24 Aug 2005 st 31 Aug 2005 st 01 Sep 2005

th

GW GW GW GW

Table of Contents 1 Introduction ....................................................................................................................................................... 3 1.1 What is NHibernate?................................................................................................................................... 3 1.2 What problems does it solve?..................................................................................................................... 3 1.3 Other similar frameworks ............................................................................................................................ 3 1.4 History of NHibernate.................................................................................................................................. 3 Example Application......................................................................................................................................... 4 User Interface .................................................................................................................................................... 4 3.1 Main Window .............................................................................................................................................. 4 3.1.1 Actions ................................................................................................................................................ 4 3.2 Orders form................................................................................................................................................. 5 3.2.1 Field Definitions .................................................................................................................................. 5 3.2.2 Actions ................................................................................................................................................ 5 Architecture and design................................................................................................................................... 5 4.1 Application Architecture .............................................................................................................................. 6 4.1.1 Database............................................................................................................................................. 6 4.1.2 NHibernate .......................................................................................................................................... 7 4.1.3 log4net ................................................................................................................................................ 7 4.1.4 Data Access Layer .............................................................................................................................. 7 4.1.4.1 DataAccessLayer.Beans namespace............................................................................................. 7 4.1.4.1.1 Customer class......................................................................................................................... 7 4.1.4.1.2 The XML mapping for Customer class (Customer.hbm.xml) ................................................... 7 4.1.4.1.3 Order class ............................................................................................................................... 8 4.1.4.1.4 The XML mapping for Order class (Order.hbm.xml) ................................................................ 8 4.1.4.2 DataAccessLayer.Services namespace ......................................................................................... 9 4.1.4.2.1 DataService class..................................................................................................................... 9 4.1.4.3 BusinessLogicLayer.Services namespace ..................................................................................... 9 4.1.4.3.1 OrderService class ................................................................................................................... 9 4.1.5 UI layer................................................................................................................................................ 9

2 3

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 2 of 9

Introduction

The need to deal with relational data is something that arises almost always with business applications. The implementation of data access layer has been drawing attention of everyone so often due to the above reason. It is not the mere implementation of the data access layer that cost a lot in a software project but the direct and side effects of wrong approaches when doing so. Finding the most cost effective approach for handling data access requirements have been the focus of many researchers including some open source groups. Object relational mapping (O/R mapping) is recognized as a concept that can solve most of the well known issues faced by developers related to data access. This concept links object oriented programming with relational data models. O/R mapping can establish a bidirectional mapping between the data in a relational database and Objects in code.

1.1 What is NHibernate?

NHibernate is an open source framework that implements the Object relational mapping concept for .NET developments. This framework covers about 95 percent of common data persistence related programming tasks while allowing the result set translation from tabular representation to graph of objects.

1.2 What problems does it solve?

The plain data access implementation using ADO.NET involves a lot of tedious, repetitive work, which consumes a lot of the time from the application developers. Such an approach can also make it so hard to separate data access implementation from the business logic or presentation layer implementations. Difficulty to reach n-tier architecture for application development can fire back at later stages of projects with unmanageable costs. NHibernate framework helps solving the above issues while integrating Object oriented programming with relational databases.

1.3 Other similar frameworks

The choice of the O/R mappers for the .NET developers is immense. Following URLs contain such listings posted by the sites interested in the subject. http://www.theserverside.net/news/thread.tss?thread_id=29914 http://sharptoolbox.com/Category74089b0a-1105-4389-b1db-eedf27e20cfb.aspx

1.4 History of NHibernate

Just like the Java environment inspired the core languages and concepts within .NET environment, the roots of NHibernate lie in the Java world. In other words NHibernate is a port of the Java Hibernate relational persistence framework. You can read more about NHibernate from the official documentation link at http://nhibernate.sourceforge.net/nh-docs/en/html/chunk/index.html

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 3 of 9

Example Application

In order to help the growing popularity of the usage of NHibernate framework, I decided to go ahead and implement a simple real world application while trying to focus a lot on an n-Tier approach that plays a vital role in enterprise application developments and maintenance. This sample application is implemented to pick a customer from an available collection in a backend data table and then retrieves the orders placed by any selected customer in a child data table. This application also allows inserting new orders to the current collection under the same customer and editing any order through the UI. The application is not made extra complex in order to leave room for the easy grasp of the concepts covered. Following is how the NHibernate framework is used inside the application to get the job done. The usage of NHibernate framework is cleanly restricted to MiddleTiers.dll assembly that implements both Data access layer and the Business logic layer of the sample. The NHibernate framework initialization code is implemented as the sole representative of data access logic which is the DataService class. That logic is called only once for the application lifetime to initialize the open source frameworks as declared in application configuration (app.config) file under <nhibernate></nhibernate> and <log4net></ log4net > sections. The business logic layer simply uses this class and appropriate persistence classes available in DataAccessLayer.Beans sub namespace to support the requirements from the UI. The UI layer does not worry about the internal implementation details of any API and simply invokes the relevant methods of classes available in BusinessLogicLayer.Services namespace to get the expected results out. The rest of this document explains the UI, architecture and design of the sample in more details

User Interface

3.1 Main Window

Figure 1: Main Window

3.1.1 Actions
Action Elements Select customers combo box View Orders Cancel Action Click on the drop down button will show the list of customers available so that user can scroll down to select the desired customer. This will invoke the Orders window (modal) populated with orders corresponding to the selected customer (Refer section 2.2) 1 Click on the Cancel button will quit the application

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 4 of 9

3.2 Orders form

Figure 2: Orders Form

3.2.1 Field Definitions

Item Orders from the customer Orders Data grid Default Populated with the customer selection of the main form Populated with the orders from the selected customer

3.2.2 Actions
Action Elements Insert an Order Update Cancel Action This will append a dummy order record to the current list of orders from the customer and commit changes to the backend User can do changes to the grid cells and click on this button to commit changes to the backend. Close the Orders form allowing access to Main form

Architecture and design

Database The backend details of this sample NHibernate Open source ORM framework Log4Net Open source logging framework DataAccessLayer/BusinessLogicLayer Middle tiers. UI Layer

This chapter provides the overview/design descriptions in terms of the following;

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 5 of 9

4.1 Application Architecture

Presentation Layer App.config file -nHibernate -log4net MainForm OrdersForm

Business Logic Layer OrderService (BusinessLogicLayer.Services) log4net Data Access Layer Persistent Objects (DataAccessLayer.Beans) DataService (DataAccessLayer.Services)

NHibernate Session SessionFactory ADO.NET

Database

Figure 3: Application architecture

4.1.1 Database
SQL 2000 server installation includes the installation of a pre-populated DB called Northwind. The following two tables from this DB is used as the data model for the application

Figure 4: Data Model

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 6 of 9

4.1.2 NHibernate
This is the Open source framework used for the Object Relational Mapping and focus of this sample application. The term object/relational mapping (ORM) refers to the technique of mapping a data representation from an object model to a relational data model with a SQL-based schema.

4.1.3 log4net
This is an Open source framework for extending the error logging implementations of applications to output log statements to a variety of output targets without adding substantial performance overheads. The official link for this framework is http://www.neoworks.com/products/free/log4net/ . N.B. Both this framework and NHibernate are to be configured through different sections in configuration file. Once these frameworks are embedded in the middle tiers, they should be able to be configured based on the requirements of the users of the middle tiers. through the app.config file of the application.

4.1.4 Data Access Layer

This is the part of the middle tier that uses NHibernate open source framework for implementing the data access needs to cater to the Business Logic layer. This includes two sub namespaces as follows.

4.1.4.1 DataAccessLayer.Beans namespace

This namespace is used for accumulating the .NET persistent class declarations corresponding to each backend table accessed by the application. The XML mapping documents based on each .NET persistent class is also kept here. When declaring the persistent class for a table, we can include only the columns required by the application to the class declarations while excluding all unwanted columns. Customer is such a class that includes only two columns out of 11 columns in the actual backend table (Customers table in figure 4) 4.1.4.1.1 Customer class Customer private string companyName private string customerId public string CompanyName public string CustomerID Figure 5: Customer persistent class 4.1.4.1.2 The XML mapping for Customer class (Customer.hbm.xml)

<?xml version="1.0" encoding="utf-8" ?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.0" namespace="DataAccessLayer.Beans" assembly="MiddleTiers"> <class name="Customer" table="Customers"> <id name="CustomerID"> <generator class="assigned" /> </id> <property name="CompanyName"/> </class> </hibernate-mapping> N.B. If you feel like the creation and maintenance of the XML mapping document is a hassle, NHibernate.Mapping.Attributes available in NHibernateContrib has a very good alternate for getting rid of the

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 7 of 9

above file altogether through attribute programming. The details and instructions for implementation is available at the link published by me at http://sourceforge.net/forum/message.php?msg_id=3233643 4.1.4.1.3 Order class Order private int orderId; private string customerId; private int employeeId; private DateTime orderDate; private DateTime requiredDate; private DateTime shippedDate; private int shipVia; private double freight; private string shipName, shipAddress, shipCity, shipRegion, shipPostalCode, shipCountry; public int OrderID public string CustomerID public int EmployeeID public DateTime OrderDate public DateTime RequiredDate public DateTime ShippedDate public int ShipVia public double Freight public string ShipName public string ShipAddress public string ShipCity public string ShipRegion public string ShipPostalCode public string ShipCountry Figure 6: Order persistent class 4.1.4.1.4 The XML mapping for Order class (Order.hbm.xml)

<?xml version="1.0" encoding="utf-8" ?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.0" namespace="DataAccessLayer.Beans" assembly="MiddleTiers"> <class name="Order" table="Orders"> <id name="OrderID" > <generator class="identity" /></id> <property name="CustomerID" /> <property name="EmployeeID"/> <property name="OrderDate" /> <property name="RequiredDate"/> <property name="ShippedDate" /> <property name="ShipVia"/> <property name="Freight"/> <property name="ShipName"/> <property name="ShipAddress"/> <property name="ShipCity"/> <property name="ShipRegion"/> <property name="ShipPostalCode"/> <property name="ShipCountry"/> </class> </hibernate-mapping> N.B. XML mapping can be avoided in the same way as described under the Customer class description.

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 8 of 9

4.1.4.2 DataAccessLayer.Services namespace

This namespace has two classes. The DataService class implements the code required for initializing open source frameworks in runtime and the code useful in using the features of frameworks. 4.1.4.2.1 DataService class DataService public void Initiate() public void Dispose() private static ILog log private static Configuration nHibernateConfig; private static ISessionFactory nHibernateFactory; public ISession NHibernateSession Figure 7: DataService class The Initiate() method of the class should be called only once at application start up and the property NHibernateSession can be used to accomplish any data access need including transactional processing. Some of such implementations are included in OrderService class (section 3.1.4.3.1) mentioned below.

4.1.4.3 BusinessLogicLayer.Services namespace

The OrderService class is the one that supports all the specific data access needs of both MainForm and OrdersForm. There could be new classes in this namespace to cater to different applications or different features of the same application when there are needs for more data access scenarios in the future. 4.1.4.3.1 OrderService class OrderService public static IList GetCustomers() public static IList GetOrdersByCustomerId(string CustomerID) public static void UpdateOrder(Order order) public static void InsertOrder (Order order) private static ILog log Figure 8: OrderService class The first two methods of this class are for initializing the MainForm and OrdersForm respectively. The other two methods are for Update and Insert an Order button handlers

4.1.5 UI layer
This layer implements only the UI forms in addition to app.config file that declares the NHibernate and log4net framework configurations. This assembly only refers to the middle tier and does not know usage details of NHibernate at all. The log4net implementation is also restricted to the middle tier for now. However the decision of extending it to UI layer to be decided based on the application requirements. The beauty of this approach could really be seen if there is a need to implement a Web based solution that provides the same features. Then it would only be the Web forms that need creation and binding to middle tiers. The entire middle tier could be used seamlessly to cater to the Web UI just like it did for Windows UI. This eliminates the need for rewriting a whole new application with lot of code duplication just to support a different UI scenario.

Copyright CodeConnexion (Pvt.) Ltd. 2005

Page 9 of 9