Atanas Hristov

Hudson: Installation and Configuration for Dot.NET Projects

2011-08-26T19:06:00.000-07:00

Hudson is a tool for continuous build, integration and deployment widely used in the Java world. Hudson can be used also with other platforms and programming languages and on many operating systems. A lot of plug-ins are available for Hudson.

For the Dot.NET world Hudson provides complete environment for continuous integration. The tool compile code with MSBuild, can run NAnt scripts, can run NUnit tests, check for code rules with FxCop or Gendarme, create documentation with Sandcastle.

The Hudson server by default provides integration with Subversion. It can be installed on Windows to run as a windows service.

The configuration of the jobs to run on the Hudson server is done completely from the web-based console of the tool. Also from there we install plug-ins.

Installing Hudson: Prerequisites

Installing Hudson on Windows is easy task. Following are the steps we needed in our case.

In this scenario we'll be using Hudson for Dot.NET development in conunction with the following tools: MSBuild, NUnit, FxCop, Gendarme, Sandcastle, so that we'll build, run unit tests, check code styles and create API documentation for our projects.

I will demonstrate using Subversion for source control system. But with Hudson you can easily use other version control systems too.

Install Java. Hudson is a Java application.

Download Link: http://www.java.com/en/download/ie_manual.jsp

Add to the system environment variable %PATH% the directory name where the java.exe is:

"C:\Program Files (x86)\Java\jre6\bin"

Open new command window and try to check the version of Java installed:

C:\>java -version

java version "1.6.0_26"

Java(TM) SE Runtime Environment (build 1.6.0_26-b03)

Java HotSpot(TM) Client VM (build 20.1-b02, mixed mode, sharing)

Install the Dot.NET SDKs you need.

You can install all together 2.0, 3.5, 4.0 and use one or another as needed. Check if the MSBuild is installed:

C:\Users\Administrator>"C:\Windows\Microsoft.NET\Framework\v2.0.50727\MSBuild"

Microsoft (R) Build Engine Version 2.0.50727.4016



C:\Users\Administrator>"C:\Windows\Microsoft.NET\Framework\v3.5\MSBuild"

Microsoft (R) Build Engine Version 3.5.30729.1



C:\>"C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild"

Microsoft (R) Build Engine Version 4.0.30319.1

You can even leverage this on that MSBuild version depending on the different projects you integrate in Hudson.

Add though the directory where the 4th version of Dot.NET is to the system PATH variable:

"%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\"

then test if you can run the MSBuild from new command prompt:

C:\>msbuild

Microsoft (R) Build Engine Version 4.0.30319.1

...

Install the NUnit framework.

NUnit is a unit-testing (xUnit) framework. It comes with GUI tests runner and command line test runner.

Download Link: http://www.nunit.org/
In our case it is the version 2.5.10 from the URL:
http://launchpad.net/nunitv2/2.5/2.5.10/+download/NUnit-2.5.10.11092.msi

Once the NUnit is installed, configure a version of the runner for the Dot.NET 4.0 framework. Copy directory:

C:\Program Files (x86)\NUnit 2.5.10\bin\net-2.0

to:

C:\Program Files (x86)\NUnit 2.5.10\bin\net-4.0

Edit the nunit.exe.config file from the new directory and add at the end of that file:

<startup>

  <requiredRuntime version="v4.0.30319" />

</startup>

just before the closing "configuration" tag. Please note the version number, make the same as you've got installed.

Add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\NUnit 2.5.10\bin\net-4.0"

Open new console window and check to see if the command line test runner is in the %PATH%:

C:\>nunit-console-x86.exe

NUnit version 2.5.10.11092

Copyright (C) 2002-2009 Charlie Poole.

...

Install FxCop.

FxCop is a tool from Microsoft that analyzes managed code assemblies and reports information about design, localization, performance and security improvements.

The tool comes a part of the Windows SDK for Windows 7 and Dot.NET 4.
All other installers of the FxCop are outdated, that's why we have to get the SDK on the machine.

Download the SDK from URL:
http://www.microsoft.com/downloads/en/confirmation.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b

Install with the default options.

The SDK was in our case installed into:

C:\Program Files\Microsoft SDKs\Windows\v7.1

The Samples into:

C:\Program Files\Microsoft SDKs\Windows\v7.1\Samples

A part of the SDK is the help library manager that gives you a chance to download locally on your computer part of the SDK documentation. The help library will be installed into:

C:\ProgramData\Microsoft\HelpLibrary\

and you (optionally) can install help content in there.

After this install finished, there is yet another installer now to run. The FxCop installer will be into directory:

C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\FXCop

Run the FxCopSetup.exe file from there.

The installer suggested in our case the following install folder:

c:\Program Files (x86)\Microsoft Fxcop 10.0\

After this installation finished, add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\Microsoft Fxcop 10.0"

Open new console window and test if you can run the application:

C:\>FxCopCmd.exe

Microsoft (R) FxCop Command-Line Tool, Version 10.0 (10.0.30319.1) X86

Copyright (C) Microsoft Corporation, All Rights Reserved.

...

Install Gendarme.

Gendarme is part of the mono-tools. It a rule based tool for finding problems in .NET applications and libraries much like the FxCop is.

Download and install the tool from the following URL:
https://github.com/downloads/spouliot/gendarme/gendarme-2.10-win32-setup.zip

The installer suggested to following target folder:

C:\Program Files (x86)\Gendarme\

After this installation finished, add to the system environment variable %PATH% the directory name:

"C:\Program Files (x86)\Gendarme"

Open new console window and test if you can run this application:

C:\>gendarme.exe

Gendarme v2.10.0.0

Copyright (C) 2005-2011 Novell, Inc. and contributors

...

Install Sandcastle, htmlhelp and SHFB.

Sandcastle produces MSDN style documetation from the source assemblies integrating the XML documentation from the source code.

Download and install Sandcastle from:
http://sandcastle.codeplex.com/

In our case the installer suggested by default the following install directory:

C:\Program Files (x86)\Sandcastle\

Download and install the Microsoft HTML Help Workshop from:
http://go.microsoft.com/fwlink/?LinkId=14188

Run the downloaded file htmlhelp.exe and follow the instructions.

The default installation path was in our case:

C:\Program Files (x86)\HTML Help Workshop

Download and install the Sandcastle Help File Builder from:
http://shfb.codeplex.com/

Unpack the downloaded zip file and run the SandcastleInstaller.exe installer application. It comes with nice wizard GUI. Follow the instructions. The installer will ask you to download and install for you all the additional applications it will need in order to work. Just answer with "Yes" on those questions.

You will skip the installation of Microsoft Help 2, this is not a necessary part to have.

It also will ask you to apply a patch to Sandcastle. Answer with "Apply Patch" on this screen.

If you wish you can install also language pack for German language.

Optionally it will download for you the MAML guide - the guide from Microsoft for the documentation markup language, web project custom providers - a package with information for producing XML documents for web applications and website projects, a HTML to MAML converter.

If you don't have Visual Studio installed skip the section :MAML Schema InteliSense"

After this step it will suggest to install for you the SHFB - Sancastle Help File Builder. Cilck on "Install SHFB" on this screen.

The SHFB in our case was installed into:

C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\

On the last screen of the wizard click on the 'Reboot' in order all the changes to take effect on your system.

Visual Studio Templates

If on the machine where Hudson will be running the visual studio is not installed you may need to come some Visual template files from developer's machine. For example copy to the machine the complete directory:

C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0

as for Visual Studio 2010 Express Edition with default installation path.

Installing Hudson: Prepare Visual Studio Project Structure for Hudson

To easily integrate a Visual Studio Project into Hudson, I would suggest the following project structure and files to be created.

Suppose we've got a project named "WebAPI"

In my project directories in Subversion I would prefer having structure like:

directory .\References - copy here all the third party DLLs you'll be referencing from the project

directory .\WebAPI - here is the project with the production code: a Visual Studio project named like the directory - WebAPI.csproj

From project properties in the Visual Studio, in section "Build" go to sub-section "Output" and enable check the box "XML documentation file". The name of the output file in "Debug" target build configuration should be the same as the specified in the Sandcastle project (below).

directory .\WebAPITests - contains the project with the unit tests for the WebAPI project: another Visual Studio project with Visual Studio project file named WebAPITests.csproj

The project with the unit tests references the project with the production code.

file WebAPI.sln - the Visual Studio solution file.

file WebAPI.shfbproj - the Sandcaslte project file

To create the Sandcastle project file run the "Sandcastle Help File Builder GUI" application. From the project properties the make the HelpFileFormat to be "HtmlHeml 1, Website".

Documentation sources are:

WebAPI\bin\Debug\WebAPI.dll

WebAPI\bin\Debug\WebAPI.XML

which is the output after compiling the WebAPI.csproj with target build configuration "Debug".

note the OutputPath from the "Project Properties" panel. The output goes to:

.\Help\

This is the directory to which we'll make link in Hudson for the API documentation of our project once the documentation is generated. That way we'll publish the generated from the continuous integration API documentation as a web-site.

file run-fxcop.bat - a batch command to run FxCop from Hudson. Example:

FxCopCmd.exe /file:WebAPI\bin\Debug\WebAPI.dll  /rule:DesignRules.dll /out:fxcop-result.xml



exit 0

note it takes the Debug output from the the WebAPI project and the output of running the FxCop application goes to file fxcop-result.xml.

file run-gendarme.bat - a batch command to run Gendarme from Hudson. Example:

gendarme.exe --xml gendarme-result.xml WebAPI\bin\Debug\WebAPI.dll



exit 0

note it takes the Debug output from the the WebAPI project and the output of running the Gendarme application goes to file gendarme-result.xml

file run-nunit.bat - a batch command to run NUnit tests from Hudson.

nunit-console-x86.exe WebAPITests\bin\WebAPITests.exe /xml=nunit-result.xml



exit 0

note it takes the Debug output from the the WebAPI project and the output of running the NUnit console goes to file nunit-result.xml

file run-sandcastle.bat - a batch command to generate documentation

MSBuild.exe /p:CopyrightText="Copyright Company" /p:FeedbackEMailAdress="address@company.com" WebAPI.shfbproj



exit 0

note we specify the MSBuild from the version 4.0 of Dot.NET and as a project file for the build project we point to the file WebAPI.shfbproj

And here we've got structure similar to this:

All the output xml files from the batch commands will be used by Hudson to show us results of running unit tests, checking code style, etc.

Installing Hudson: Installation

At this point we are ready to install the Hudson. We'll install Hudson as a Windows service on Windows.

Prepare working directory

Create directory

C:\Hudson

In this directory Hudson will be installed. From the Windows control panel set up system environment variable:

HUDSON_HOME=C:\Hudson

Open new command prompt and test the new variable:

C:\>echo %HUDSON_HOME%

C:\Hudson

In this directory Hudson will check out from Subversion our code and will run the jobs to compile and run unit tests. So, this will be the Hudson's working directory. There Hudson will accumulate files with historical information.

Install Hudson

Create directory where to install the Hudson server:

C:\Program Files (x86)\Hudson

Download into this directory the latest version of Hudson from:
http://java.net/projects/hudson/downloads/download/war/hudson-2.1.0.war

Note: you can always upgrade Hudson automatically to the latest version directly from the Hudson's web console - after the Hudson installed as windows service.

Rename the file as removing the version information from the file name. Check the install directory of the Hudson server:

C:\Users\Administrator>dir "C:\Program Files (x86)\Hudson"

08/20/2011  09:24 AM    <DIR>          .

08/20/2011  09:24 AM    <DIR>          ..

08/20/2011  09:23 AM        38,948,136 hudson.war

Run Hudson

Now open a command prompt and go to this directory, run the Hudson server from there:

java -jar hudson.war

C:\Program Files (x86)\Hudson>java -jar hudson.war

Running from: C:\Program Files (x86)\Hudson\hudson.war

[Winstone 2011/08/20 14:11:50] - Beginning extraction from war file

Aug 20, 2011 2:11:52 PM hudson.WebAppMain contextInitialized

It will start doing  thinks, just wait until it says: "Completed initialization".

...

INFO: Home directory: C:\Hudson

...

note: look on the log messages, somewhere at the beginning it should say:

hudson home directory: C:\Hudson

Hudson will start by default HTTP web server on port 8080, open the following URL into your web browser, this is the Hudson's console there:
http://localhost:8080

Install as windows service

Click on Hudson/Manage Hudson, then on “Install as Windows Service”. It will take time to finish.

Watch the application on the command prompt, it will restart as windows service. After the installation complete confirm to restart.

You can close the window with the command prompt. From here on only work happens on the web interface of Hudson!

Note: You can delete the service using this command:

sc delete hudson

Note: Later you can always upgrade to the latest version your copy of Hudson.

From the web console of Hudson go to Hudson\Manage Hudson and click on "Upgrade Automatically".
Wait for Hudson to finish the installation.
Click on "Restart when no jobs are running".

Install Plug-Ins

Go to Hudson\Manage Hudson and click on Manage Plugins. Click on "Available" and select:

MSBuild Plugin

NAnt Plugin

NUnit Plugin

Analysis Collector Plugin

Static Code Analysis Plug-ins

Task Scanner Plugin

Violations

Warnings Plugin

Scroll down the page and click on "Install". After Hudson installed all those plugins, click on "Restart when no jobs are running".

Go to Hudson\Manage Hudson\Pugin Manager, open tab Installed and check if all these Plugins are installed:

Go to Hudson\Manage Hudson and click on "Configure System".
Scroll down to "MSBuild Builder" and click on "Add".

Write for name "MSBuild Dot.NET 4.0".
Write for path the full path name of the msbuild.exe file for Dot.NET 4.0, in our case it was

"C:\Windows\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe"

You can add for other Dot.NET frameworks if you need. Later from the concrete jobs you'll use them as appropriate in your case.

Scroll down, click "Save".

Configure Hudson: Add Jobs

Now we can add our project for continuous integration as a job on the Hudson server.

Continuous build

This is a build which will be checking every minute for changes in the Subversion repository, if they are some changes will check out the latest changes, build our project and run the unit tests.

Click on Hudson\New job. Set the name of the job, in this example "WebAPI continuous build" and select the option "Build a free-style software project". Click on "OK".

In section "Source Code Management" select "Subversion". Set the Repository URL as appropriate.

Move the focus to another field. Hudson will try to access your Subversion server and if the authentication failed will show red colored message next to the text box with the repositiry URL. The message should contain an html link "enter credentials". Click the link and follow the instructions. Eventually you'll be able to give your user name and password if you choose this form of authentication.

Once you successfully finish this, you'll come back to the previous page.

In section "Build Triggers" select "Poll SCM" and specify "*/1 * * * *" to check every minute for changes in the source repository.

In section "Buld" click on "Add build step", then "Build a Visual Studio project or solution using MSBuild". Select/write (we are following the example file and VS project names from above):

MsBuild Version   : MS Buld Dot.NET 4.0

MsBuild Build File :  WebAPI.sln

Command line arguments :  /p:Configuration=DEBUG

Click on "Add build step", then on "Execute Windows batch command". Write:

run-nunit.bat

In section "Post-build Actions" select "Publish NUnit test result report and enter for "Test report XMLs:

nunit-result.xml

Click on Save to save the job. In short time Hudson should start a build for this job. If the build failed, check the "Console Output" from the job menus.

Note: you can at any time schedule run for a job. Go to the home page of the tool, click on the link to the job "WebAPI continuous build", from the left-side menus click on "Build now".

You can check the result of your unit tests from the link "Latest Test Result". Also you can browse your source code tree from the "Workspace" link and check for latest changes from the link "Resent Changes".

Now that we added a build project we've got nice dashboard on the home page of our Hudson server:

Extended build

This is a build which will run once in a day and will run code-style checks and will create documentation for the API.

Click on Hudson\New job. Set the name of the job, in this example "WebAPI extended build" and select the option "Build a free-style software project". Click on "OK".

In section "Source Code Management" select "Subversion". Set the Repository URL as appropriate.

Move the focus to another field. Hudson will try to access your Subversion server and if the authentication failed will show red colored message next to the text box with the repositiry URL. The message should contain an html link "enter credentials". Click the link and follow the instructions. Eventually you'll be able to give your user name and password if you choose this form of authentication. Once you successfully finish this, you'll come back to the previous page.

In section "Build Triggers" select "Build periodically" and specify "40 02 * * *" - just an example - to run the job once a day at 02:40 PM.

In section "Buld" click on "Add build step", then "Build a Visual Studio project or solution using MSBuild". Select/write (we are following the example file and VS project names from above):

MsBuild Version   : MS Buld Dot.NET 4.0

MsBuild Build File :  WebAPI\WebAPI.csproj

Command line arguments :  /p:Configuration=DEBUG

Note: this only is going to build the project with production code, we don't need to build the complete Visual Studio solution, but won't be wrong as well.

Add one after other the following Windows batch commands clicking on the button "Add build steps" as "Execute Windows batch command":

run-fxcop.bat



run-gendarme.bat



run-sandcastle.bat

From the "Post-build Actions" section select "Publish Javadoc" and enter "help" as "Javadoc directory".

Then select "Report Violations" and configure the rows for fxcop and gendarme reports as appropriate.

Click on "Save" button down the page.

Click on "Build now" from the left-side menus of the project.

Once the build finished you can check for the generated documentation and the code violations.

Take some time to explore both of them, you'll find very useful suggestions in there.

Hudson: Links

Hudson CI Server: http://hudson-ci.org/
FxCop: http://msdn.microsoft.com/en-us/library/bb429476%28v=vs.80%29.aspx
NUnit: http://www.nunit.org/

Links to some of the Plugins we mentioned:
MSBuild Plugin: http://wiki.hudson-ci.org/display/HUDSON/MSBuild+Plugin
NAnt Plugin: http://wiki.hudson-ci.org//display/HUDSON/NAnt+Plugin
NUnit Plugin: http://wiki.hudson-ci.org//display/HUDSON/NUnit+Plugin
Analysis Collector: http://wiki.hudson-ci.org//display/HUDSON/Analysis+Collector+Plugin

Atanas Hristov

TDD with jsTestDriver - find image size with Java Script

2011-02-03T18:00:00.000-08:00

In my last post I created small java script function that finds the size of image by URL. I used YUI 3 test framework for doing unit tests while I worked on that function.

Because YUI 3 test framework is in-browser framework we are facing the challenge how to automate our unit tests and how to apply TDD with automated continuous build and automated continuous integration. As we have to manually re-run tests it is a challenge to keep testing our java script on several web browsers on different platforms.

jsTestDriver is automation tool for unit testing for java script. It is a server written in Java. From several several browsers you open URL hosted on the jsTestDriver server. The jsTestDriver can then automatically re-run the unit tests whenever they are some changes in the source code and thereof shows if the unit tests failed or passed on the currently connected web browsers. That way you can test as many as you like combinations of browsers and platforms in an automated way.

I'll be working on Linux for the examples, but the jsTestDriver works on Windows too. Also, it is always a good idea to develop your java script libraries outside your web projects and ideally to use in your web projects already tested, optimized and minified java script file.

The installation of jsTestDriver is very simple. Download the jar file from the project's web site:
http://js-test-driver.googlecode.com/files/JsTestDriver-1.2.2.jar

Just copy the jar file on directory where it is convenient for you. Here is a snipped from my directory structure:

ahristov@medion:~/Desktop/Projects/js/bin$ ls

compiler.jar  JsTestDriver-1.2.2.jar  SoyToJsSrcCompiler.jar

You should export environment variable $JSTESTDRIVER_HOME (%JSTESTDRIVER_HOME% on Windows, go to My Computer -> Properties -> System -> Advanced and change the Environment Variables to make the changes permanent).

ahristov@medion:~/Desktop/Projects/js/bin$ cat ~/.bashrc | tail -n 7



export PATH=".:$HOME/bin:$PATH:/var/lib/gems/1.9.1/bin"

export JSBIN="$HOME/Desktop/Projects/js/bin"

export JSTESTDRIVER_HOME="$JSBIN"

The directory structure for our small project looks like this:

ahristov@medion:~/Desktop/Projects/js/proj/play$ ls

build  deps  jsTestDriver.conf  src  test

As I mentioned in my last post build you can ignore, I normally have build directory where I would generate minified, tested java script - the stuff that I'll be using in my web project. We don't need the deps folder this time, as we will not have any dependencies on 3rd party java script.

The file jsTestDriver.conf is a configuration file for the jsTestDriver with the following content:

ahristov@medion:~/Desktop/Projects/js/proj/play$ cat jsTestDriver.conf

server: http://localhost:4224



load:

- src/*.js

- test/*.js

It states, we'll run the jsTestDriver on port 4224, the server will load all the java script files from directories src and test. All the load paths are relative to the directory where the jsTestDriver.conf file is. Please note that the order the directories and file names are important. In our case the jsTestDriver will first load the source code java script files, then the unit test java script files. More information for the jsTestDriver configuration file you can find on the projects wiki page:

http://code.google.com/p/js-test-driver/wiki/ConfigurationFile

src - this directory holds just one java script file in which is the source code of function ImgSize()

ahristov@medion:~/Desktop/Projects/js/proj/play$ cat src/ImgSize.js

/**

* Calculate the size of image.

* @param {string} url Url of the image which size to find

* @param {function(number, number)} onSizeCalculated Callback function to run once

*   the size of the image calculated

*/

function ImgSize(url, onSizeCalculated) {



// Once the image is loaded, the calls the callback function onSizeCalculated

function setDimensions() {

// scope changed: this = Image object

if (onSizeCalculated) {

onSizeCalculated(this.width, this.height);

}

}



// Initialization:

// - sets callback on image loaded - setDimensions;

// - loads the image.

function init() {

var img = new Image();

img.name = url;

img.onload = setDimensions;

img.src = url;

}



// Run initialization

init();

};

This is the same function that we developed and tested with the YUI 3 test framework in my last post.

test is the directory where the java script files with the unit tests are

ahristov@medion:~/Desktop/Projects/js/proj/play$ ls test/

ImgSize  ImgSize.html  ImgSize-test.js

ahristov@medion:~/Desktop/Projects/js/proj/play$ ls test/ImgSize

137x38.gif

File ImgSize.html is from my last post, you can ignore it for now. The file 137x38.gif is an image with the size 137px / 38px which I'll use for the purpose of the unit testing.

If we were about to test synchronous java script we would use the traditional TestCase runner. Our ImgSize-test.js would look like:

// holds tests for the ImgSize() function

//

TestCase("ImgSizeTest", {

"test image size should be 137x38": function() {

new ImgSize('http://192.168.1.4:8080/js/proj/play/test/ImgSize/137x38.gif',

function assertOnSizeCalculated(width, height) {

assertEquals(137, width);

assertEquals( 38, height);

})

}

});

How that we are going to test asynchronous calls we should use the AsyncTestCase runner, so that our ImgSize-test.js contains:

var ImgSizeTest = AsyncTestCase('ImgSizeTest');



ImgSizeTest.prototype.testImgSizeFunction = function(queue) {



expectAsserts(2);



var onSizeCalculated = queue.add(function() {

assertEquals(137, arguments[0][0]);

assertEquals( 38, arguments[0][1]);

});



new ImgSize('http://192.168.1.4:8080/js/proj/play/test/ImgSize/137x38.gif',

onSizeCalculated);

};

The queue parameter accepts inline function via method add(), the function will run whenever the browser downloaded the image and calculated the size of the image.

As you can see, the image file should be accessible from URL from the testing browsers, so I just put the gif image on web server on the following URL above. Keep in mind, you have to adjust that the way you need it.

The syntax is very similar to YUI 3 test and even simpler. Whenever the browser loaded the image, we are going to check if the ImgSize() function gets the proper image size information. Please note that we are not dealing with DOM and UI. If you want to test DOM operations you can add HTML to the unit test files, for more information check the wiki pages of the jsTestDriver project:

http://code.google.com/p/js-test-driver/wiki/HtmlDoc

The page containing documentation for asynchronous unit tests with jsTestDriver is:
http://code.google.com/p/js-test-driver/wiki/AsyncTestCase

How it is time to start the jsTestDriver server:

ahristov@medion:~$ java -jar $JSTESTDRIVER_HOME/JsTestDriver-1.2.2.jar --port 4224

Next step is to open the URL where the jsTestDriver server is listening:

Enter the URL to the server in the web browser and click in "Capture This Browser"

This browser started waiting for automation from the server to run unit tests. Let's add another browser to the testing:

Clicking on "Capture This Browser":

Connect several web browsers to the jsTestDriver server.

As we are ready to start our unit tests, we have to first run the jsTestDriver server. From the directory where the configuration file jsTestDriver.conf is we run:

ahristov@medion:~/Desktop/Projects/js/proj/play$ java -jar $JSTESTDRIVER_HOME/JsTestDriver-1.2.2.jar --tests all

Which gets the following output:

The test passed on 3 different browsers.

Now, how to repeat the tests automatically whenever the source code of our java script changed?

If you have Ruby installed on your system, you can install the jstdutil package:

gem install jstdutil

It provides a wrapper to jsTestDriver so instead of writing every time this long command lines on the shell, you just - from the directory where the jsTestDriver.conf file is run:

ahristov@medion:~/Desktop/Projects/js/proj/play$ jsautotest

Every time we do changes on our java script source code the jsTestDriver will automatically start doing the unit tests and then will report the result:

Let's change the test, make the test fail, change the following line:

assertEquals( 38, arguments[0][1]);

assertEquals( 39, arguments[0][1]);

as the jsautotest is running. At the moment we save the javascript file, jsautotest automatically re-runs the tests sending the appropriate command to the jsTestDriver server and all currently captured browsers start running the tests. We get error in our tests and the jsautotest console explains this with output similar to:

Changing the assert back from 39 to 38 in the ImgSize-test.js makes jsautotest again to re-run the tests on the jsTestDr4iver server, and this time they successfully pass.

The jsTestDriver project has the following URL:
http://code.google.com/p/js-test-driver/

The home page of the jstdutil Ruby package:
http://cjohansen.no/en/javascript/jstdutil_a_ruby_wrapper_over_jstestdriver

Atanas Hristov

TDD with YUI 3 - find image size with Java Script

2011-02-02T18:10:00.000-08:00

Finding size of image using java script involves asynchronous techniques and callback functions. I'm showing how the in-browser YUI 3 test framework can be used for TDD. They are other options for in-browser test frameworks like QUnit and JsUnit, the techniques here should be equally usable.

I came across the need to find the size of image given by URL and using java script. The task was about scaling the width and the height of html elements proportionally for the needs of the UI and accordingly to the size of the image.

To find the size of image you have to first wait until the image downloaded - unless the image is in the browser's cache. Once the image downloaded and loaded into Image object in java script you can check for the size.

Let's first specify the desired java script function. Let's name it ImgSize() with the following signature:


  function ImgSize(url, onSizeCalculated)

Parameter url is the url to the image to look for
Parameter onSizeCalculated is a reference to callback function to call once the image downloaded and we have calculated the size of the image. The callback function - once the size of the image is calculated - will receive two numeric arguments: the width and height - the size of the image.

For the directory structure of this project I'll suggest working directory with the following subdirectories:


    ahristov@medion:~/Desktop/Projects/js/proj/play$ ls
    build  deps  src  test

I usually start with similar directory structure (well, not to mention for things like tags, branches, revisions, etc. but that's another theme :-).
The subdirectory build I use to save the output of my work. In our example you can just ignore it.

deps/yui - contains the complete YUI3 library. Again, we'll be using only the test framework from the YUI. The test framework you'll find in the following subdirectory:


  ahristov@medion:~/Desktop/Projects/js/proj/play$ ls deps/yui/build/test/
  assets  test-debug.js  test.js  test-min.js

test - this directory contains the HTML test fixture for the ImgSize() function. It is a html file that hosts the java script unit tests. Also there is a gif image with the size of 137px / 38px in subdirectory test/ImgSize the size of which will be calculated from the unit tests and against this we'll be checking how the ImgSize() function works.


  ahristov@medion:~/Desktop/Projects/js/proj/play$ ls test
  ImgSize  ImgSize.html
  ahristov@medion:~/Desktop/Projects/js/proj/play$ ls test/ImgSize
  137x38.gif

src - this directory holds just one java script file in which is the source code of function ImgSize()


  ahristov@medion:~/Desktop/Projects/js/proj/play$ ls src
  ImgSize.js

I'll show you first the content of the test fixture - the html document ImgSize.html from my test suite:


  ahristov@medion:~/Desktop/Projects/js/proj/play$ cat test/ImgSize.html
  <html>
  <head>
    <script type="text/javascript" charset="utf-8" src="../deps/yui/build/yui/yui-min.js"></script>
    <script type="text/javascript" charset="utf-8" src="../src/ImgSize.js"></script>
  </head>
  <body>
    <script type="text/javascript">
    
      // Create new YUI instance, and populate it with the required modules
      YUI().use('console', 'test', function(Y) {
      
        Y.namespace("ImgSize.Test");
        
        Y.ImgSize.Test.ImgSizeTestCase = new Y.Test.Case({
        
          name: "Test image size",
          
          test137x98 : function () {
              new ImgSize('./ImgSize/137x38.gif',
                function assertOnSizeCalculated(width, height) {
                  Y.Assert.areEqual(137, width, "Width should be same");
                  Y.Assert.areEqual( 38, height, "Height should be same");
                });
              }
          });

        Y.Test.Runner.add(Y.ImgSize.Test.ImgSizeTestCase);
        
        //run the tests
        Y.Test.Runner.run();
        
      });
  </script>
  </body>
  </html>

Into the head section I added script link to the YUI library yui-min.js and another script link to the ImgSize.js - the file where the source code of the function under test - ImgSize() - will be.

As you can see, the html markup is very basic. The only content of the body tag - just before closing it - is a script tag where the unit tests are.

YUI.use('console', 'test' - The YUI has a very powerful modular structure. The use() function fetches for us only the functionality we'll need without downloading for us complete framework . So we only include the test runner console and the test framework. That is the only we'll fetch out of the whole YUI framework whenever the browser opens the html page with the unit tests. I really like the modularity of frameworks like YUI or Closure.

Y.namespace() - this is very useful feature of the YUI library that helps you to organize your code into namespaces. We are not going into more details concerning the YUI namespaces in this example.

new Y.Test.Case() creates an instance of test case. The test case will be named "Test image size". After the name of the test case we define one or more unit tests - functions as named properties.

test137x98 - this is the only test in this test case - we ask the ImgSize() function to calculate the size of the image 137x38.gif giving as a callback function assertion function. Whenever the image downloaded and the size of the image calculated, the assertion function will be invoked and will run as YUI test.

You probably will recognize many similarities between YUI test and frameworks like nUnit of Junit. You can for example also specify "setUp" or "tearDown" functions. Besides this the YUI test framework also gives you mocking, asynchronous tests, etc. It is a very nice library.

In case we were testing DOM manipulations and more UI stuff, then we would add HTML markup for that. In this case we are dealing with pure java script function and the abilities of the Image java script object.

The YUI test won't be so good in case we want to automate and run our tests frequently on rich set of browsers. In such cases we would be using automated testing frameworks like jsTestDriver for example.

Finally here is the source code of the ImgSize() function:


  ahristov@medion:~/Desktop/Projects/js/proj/play$ cat src/ImgSize.js
  /**
  * Calculate the size of image.
  * @param {string} url Url of the image which size to find
  * @param {function(number, number)} onSizeCalculated Callback function to run once
  *   the size of the image calculated
  */
  function ImgSize(url, onSizeCalculated) {
  
    // Once the image is loaded, the calls the callback function onSizeCalculated
    function setDimensions() {
      // scope changed: this = Image object
      if (onSizeCalculated) {
       onSizeCalculated(this.width, this.height);
      }
    }
    
    // Initialization:
    // - sets callback on image loaded - setDimensions;
    // - loads the image.
    function init() {
      var img = new Image();
      img.name = url;
      img.onload = setDimensions;
      img.src = url;
    }
    
    // Run initialization
    init();
  };

The first action that happens inside ImgSize() is into the Init() function. We create object of type Image and before the assignment to property src we make sure we have assigned Image.onload event handler. Once the image is loaded, we check if onSizeCalculated callback was sent and call the callback function - see function setDimensions(). In our case is will be unit test assertion.

We just have to open the html test fixture file into our web browser. Here's how the test report looks in Chrome's Developer Tools. You should watch the results of the unit test execution into the console window:

More information for the YUI test framework you'll find here:

http://developer.yahoo.com/yui/3/test/

The YUI Test is part of the Yahoo! User Interface Library and I'll be using version 3 of the YUI. To download the YUI 3 go to the following URL:

http://developer.yahoo.com/yui/3/

Atanas Hristov

Design Patterns – State Pattern

2010-03-15T10:05:00.000-07:00

The State design pattern is a behavioural pattern. The behaviour of object changes accordingly to its internal state. Instead of implementing if-then-else like structure inside the object to switch the behaviour, we move the logic to property "State" which has method Handle() and call this method. We change the behaviour of the object as we just switch the value of the "State" property.

The class which behaviour will change accordingly to its state is named Context. The Context class contains property State which is of type that implements common IState interface.

We have different implementations of IState - StateOne, StateTwo etc. We assign new IState object to the property "State" of the Context object and the behaviour of the Context object changes.

Traffic Light

Imagine we are going to implement traffic light. Accordingly to Wikipedia we have three possible lights: red; amber and green. The traffic light cycle may vary, but we are going to implement 3-way traffic light cycle.

Red light - Means prohibits the traffic from proceeding.

Green light - Then follows the green light that allows to proceed.

Yellow light - Next is yellow light denoting if safe to, prepare to stop.

We will use the State pattern to implement a traffic light. The traffic light (TrafficLight) object is the context object. The traffic light has public properties for the color of the light currently turned on, it knows for how long this light should stay, and knows light of which color will follow after that. But setting these properties is done by State object.

We have 3 different states for the three traffic light colors. All they have method Handle() which is invoked by the TrafficLight object.

IState interface

All the concrete State classes have to implement interface ITrafficLightState. The concrete traffic light state handles request from the Context object and thereof the behaviour of the Context object changes.


        interface ITrafficLightState
        {
            void Handle(TrafficLight trafficLight);
        }

State implementations

For the different traffic light colors we implement three different State objects. All they implement interface ITrafficLightState:


        // State "Red Light"
        class RedLightState : ITrafficLightState
        {
            public void Handle(TrafficLight trafficLight)
            {
                trafficLight.Color = "Red"; // Switch the traffic light color
                trafficLight.Pause = 5; // For 5 seconds
                trafficLight.NextState = new GreenLightState(); // Then green light follows
            }
        }

        // State "Amber Light"
        class AmberLightState : ITrafficLightState
        {
            public void Handle(TrafficLight trafficLight)
            {
                trafficLight.Color = "Amber"; // Switch the traffic light color
                trafficLight.Pause = 2; // For 2 seconds
                trafficLight.NextState = new RedLightState(); // Then red light follows
            }
        }

        // State "Green Light"
        class GreenLightState : ITrafficLightState
        {
            public void Handle(TrafficLight trafficLight)
            {
                trafficLight.Color = "Green"; // Switch the traffic light color
                trafficLight.Pause = 5; // For 5 seconds
                trafficLight.NextState = new AmberLightState(); // Then Amber light follows
            }
        }

TrafficLight context object

How we are ready to implement the TrafficLight context object:


        // Context - "Traffic Light", has internal state - one of the above.
        // The behaviour changes accordingly to the current state
        class TrafficLight
        {
            // Has properties that define it's behaviour
            public int Pause { get; set; }
            public string Color { get; set; }

            // Has internal State
            public ITrafficLightState NextState { get; set; }

            // Sets the default state
            public TrafficLight()
            {
                this.NextState = new RedLightState();
            }


            // Receives request ...
            public void Request()
            {
                // ... then:
                // Delegates to the internal State to handle.
                NextState.Handle(this);

                // The behaviour has changed, color, time of light, etc.
                Console.WriteLine(Color);
                System.Threading.Thread.Sleep(Pause * 1000);
            }
        }

And with this we are ready to give a try of our implementation, which looks like this now:

To demonstrate the traffic light we run an infinite loop and call the method Request() on instance of TrafficLight:


        static void Main(string[] args)
        {
            // Demonstrate how TrafficLight works
            TrafficLight trafficLight = new TrafficLight();
            while (true)
                trafficLight.Request();
        }

Usage of State pattern

In our example the state of the Context object was changed from the state object itself. But it is not necessarily to be done this way. We can implement a Coffee Machine to run Short, Tall, Grand coffee. Then the state would be changed pressing a button on the Machine. Or we could use State pattern to switch between simple and advanced preview on a form. Then probably the Handle() function will just change the preview but not the user preferences.

Atanas Hristov

Implementing and Using Repositories with NHibernate

2010-01-04T10:17:00.000-08:00

Following the podcasts of the MVC Storefront Project at the time learning the ASP.NET MVC framework was for me really good introduction to the ideas of the Domain Driven Design (DDD).

Now, months later and still new to the DDD, but very enthusiastic, I’ll try to sketch some ideas I learned so far and in practice to implement a complete example. In particular I’ll be utilizing the Repository pattern and implement it with NHibernate as data access framework. I’m using NHibernate but I keep in mind to provide a layer of abstraction and to make it possible to switch to another data access provider (Entity Framework for example).

The Repository Pattern

Accordingly to Martin Fowler:

“A Repository mediates between the domain and data mapping layers, acting like an in-memory domain object collection. Client objects construct query specifications declaratively and submit them to Repository for satisfaction. Objects can be added to and removed from the Repository, as they can from a simple collection of objects, and the mapping code encapsulated by the Repository will carry out the appropriate operations behind the scenes. Conceptually, a Repository encapsulates the set of objects persisted in a data store and the operations performed over them, providing a more object-oriented view of the persistence layer. Repository also supports the objective of achieving a clean separation and one-way dependency between the domain and data mapping layers“.

The Repository encapsulates the actual storage and querying and keeps the client to focus on the model. We can use dependency injection and inversion of control to switch real and fake repositories for the needs of testing. We have also all the querying logic in centralized part of the application and it makes the support easier. Our application depends on simple in-memory collections, etc.

The Business Model

We have pretty simple bookstore model. We have only two kinds of objects: Books and Authors. A book can be written by one or many authors. One author can take part of writing one or more books. So, the relation between them is many-to-many.

The final database model could be similar to this:

Domain Entity Objects and Approval Services

In DDD Entity is an object fundamentally defined by thread of continuity and identity.

Value object is then an object that has properties (shapes) and does not have identity. Usually these are read-only object we use as data transfer object (DTO).

In an “ideal” world the entity objects does not have properties, but exposes operations (methods). To change the internal state of entity object we call its methods and send there value objects as parameters.

In this example our entity objects will have properties and we directly will access them to change the information contained in our entities.

When changing the properties of the entity objects we’ll need a possibility to validate the state of the entity object. We use the validation for example to show the end user an error message and prevent storing object to the database if it does not have valid state. The book object for example should have a title. We need a way the entity does validation of itself. Also, same entity object can be valid in one context, but in another context with same containing data to be invalid. We’ll inject a validator object that will implement the rules of the validation.

The validator object is kind of a Service object and is an operation. It does not belong to any object, but just checks if the properties of the entity object pass some rules. The dependency injection will be exposed via property which we name “Approval”.

The EntityBase class is from where all our entities will inherit:


    /// <summary>
    /// EntityBase represents objects primary defined by it's identity (Id).
    /// The type of the identity, usually but not necessariily is of 
    /// type integer and is automatically assigned primary key.
    /// 
    /// All of the domain entities inherit this base class.
    /// All of the domain entities have an identity and are able
    /// to state if the data they contain is valid.
    /// 
    /// To check if the entity object contains valid data, they expose 
    /// property named Approval which is a concrete implementation of
    /// ApprovalBase. The entity's Validate() method just wraps
    /// the Approval.Validate(). The validation of entity returns list 
    /// of error messages and there is also a shortcut methnod IsValid()
    /// which just gives back true if the validation was successful 
    /// or false if the validation has failed.
    /// 
    /// The entity objects implement IComparable interface and equality tests.
    /// The have Equals() method to check if two variables point to same instance 
    /// of the same entity class and also they have equality operators that check
    /// if the IDs are same.
    /// </summary>
    public abstract class EntityBase<TIdentity> where TIdentity : IComparable
    {
        // Gets or sets the identity.
        public virtual TIdentity Id { get; set; }

        protected EntityBase(TIdentity Id) { this.Id = Id; }

        protected EntityBase() { }

        // Approval object that does the validation.
        public abstract ApprovalBase Approval { get; set; }

        // Validation
        public virtual IList<String> Validate()
        {
            if (Approval != null)
                return Approval.Validate(this);
            else
                return new List<String>();
        }

        // Validation shortcut
        public virtual bool IsValid()
        {
            return (Validate().Count == 0);
        }


        // Equality tests /////////////

        // Determines whether the specified entity parameter
        /// is equal to the current object (is the same reference)
        public override bool Equals(object entity)
        {
            if (entity == null || !(entity is EntityBase<TIdentity>))
                return false;

            return (this == (EntityBase<TIdentity>)entity);
        }

        // Check if two entities have same ID
        public static bool operator ==(EntityBase<TIdentity> entity1, EntityBase<TIdentity> entity2)
        {
            object obj1 = entity1 as object;
            object obj2 = entity2 as object;

            if ((obj1 == null) && (obj2 == null))
                return true;

            if ((obj1 == null) || (obj2 == null))
                return false;

            if (entity1.GetType() != entity2.GetType())
                return false;

            if (entity1.Id.CompareTo(entity2.Id) != 0)
                return false;

            return true;
        }

        // Check if two entities have different ID
        public static bool operator !=(EntityBase<TIdentity> entity1, EntityBase<TIdentity> entity2)
        {
            return (!(entity1 == entity2));
        }

        // GetHashCode() if the Id.
        public override int GetHashCode() { return this.Id.GetHashCode(); }
    }

Then we inject an approval object to our entities and the approval objects inherit from ApprovalBase:


    /// <summary>
    /// The entity objects have property based
    /// dependency injection with approval object.
    /// 
    /// If the entity has approval object,
    /// the entity can be validated to prevent saving
    /// entities with incorrect values, or to inform the 
    /// end user that the data he has entered is invalid.
    /// 
    /// The validation can be changed according to the context
    /// the entity is in. In one situation the entity may be valid, but
    /// in other situation the same entity with same properties
    /// may not be valid.
    /// 
    /// The ApprovalBase is an abstract class from wich the concrete approval
    /// classes will inherit. The ApprovalBase has method Validate wich returns 
    /// List of ApprovalErrorMessage error messages.
    /// </summary>
    public abstract class ApprovalBase
    {
        public abstract IList<String> Validate<TEntity>(TEntity entity);
    }

Finder Objects

I found the ideas from Russell East’s blog "Implementing the Repository and Finder patterns" to be very promising and I think it is a very advanced way of implementing repositories.

For the original idea, please refer to:

http://russelleast.wordpress.com/2008/09/20/implementing-the-repository-and-finder-patterns/

I'm just following the same pattern here. The querying repositories depend on finder and persistence repositories.

One goals of Russell's idea is to keep independent from concrete Object Relational Mapper (ORM). Other goal is to have typed repositories - one per entity - and thereof make it possible to inject finder objects to the repositories. Also, he makes possible to inject the concrete persistance layer via inversion of control and provides fully testable implementation of repository.

All the entity finders extend a base IEntityFinder interface. The generic type is constrained by the EntityBase type.
The IEntityFinder interface is not to be used directly, but to be extended by typed Repository interfaces.


    public interface IFinder<TEntity, TIdentity>
        where TEntity : EntityBase<TIdentity>
        where TIdentity : IComparable
    {
        // Has a DataSource property of IQueryable on which 
        // we use LINQ for quering.
        IQueryable<TEntity> DataSource { get; set; }

        /// Get count of objects/records.
        int Count();

        /// Find by id. We have entityConcrete = repositoryConcrete.Find.ById(123) like usage.
        TEntity ById(TIdentity id);
    }

All the finder object inherit from FinderBase class. The Finder objects implement search logic/functions using LINQ. The classes inherited from RepositoryBase (see below) have then object Find, which method names by convention look like "ById", "ByName", etc. The concrete finders have to implement at least ById method.



    public abstract class FinderBase<TEntity, TIdentity>
        : IFinder<TEntity, TIdentity>
        where TEntity : EntityBase<TIdentity>
        where TIdentity : IComparable
    {
        public IQueryable<TEntity> DataSource { get; set; }

        /// Gets count of records.
        public int Count()
        {
            return DataSource.Count();
        }

        /// Find one entity by ID.
        public abstract TEntity ById(TIdentity id);
    }

Base Repository Class

Let’s first define how the concrete persistence layer should look like.

The concrete ORM specific implementation is abstracted with interface IPersistor.

The repository takes care for querying; the persistence repository takes care for persistence and depends on ORM specific implementation.

The basic operations in the contract declared by this interface are: get entity by id; save entity to persist; delete entity from persist repository; get the query object on top of which to implement concrete LINQ queries.


    public interface IPersistor<TEntity, TIdentity>
    {
        TEntity Get(TIdentity id);
        void Save(TEntity entity);
        void Delete(TEntity entity);
        IQueryable<TEntity> Query();
    }

Now we are about to finish the base repository class.

All the repositories extend a base IRepository interface. The generic type is restricted to be EntityBase type.
The basic operations in the contract are much the same like the defined in IPersistor, but we don't expose IQueryable to public, as we implement all the querying logic into the concrete repositories.


    public interface IRepository<TEntity, TIdentity>
        where TEntity : EntityBase<TIdentity>
        where TIdentity : IComparable
    {
        TEntity Get(TIdentity id);
        IList<String> Save(TEntity entity);
        void Delete(TEntity entity);
        // hidden // IQueryable<TEntity> Query();
    }

The RepositoryBase is an abstract class from which all concrete repositories inherit from.
The repositories are injected with concrete entity types using the typed interface, so we have one repository per entity.
The repository class must be supplied an instance of IPersistor and an instance of IFinder.


    public abstract class RepositoryBase<TEntity, TIdentity>
        : IRepository<TEntity, TIdentity>
        where TEntity : EntityBase<TIdentity>
        where TIdentity : IComparable
    {
        private readonly IPersistor<TEntity, TIdentity> persistor;
        public IPersistor<TEntity, TIdentity> Persistor { get { return persistor; } }

        private readonly IFinder<TEntity, TIdentity> finder;
        public IFinder<TEntity, TIdentity> Finder { get { return finder; } }

        private RepositoryBase() { }

        public RepositoryBase(
            IPersistor<TEntity, TIdentity> persistor,
            IFinder<TEntity, TIdentity> finder)
        {
            this.persistor = persistor;
            this.finder = finder;
            this.finder.DataSource = Query();
        }

        // Get entity by ID
        public virtual TEntity Get(TIdentity id)
        {
            return persistor.Get(id);
        }

        /// <summary>
        /// Validate and Save the entity. If the validation failed, will not save the entity,
        /// but returns back list of error messages.
        /// </summary>
        public virtual IList<String> Save(TEntity entity)
        {
            if (entity == null)
                throw new ArgumentNullException("entity");

            IList<String> errors = entity.Validate();

            if (errors.Count == 0)
                persistor.Save(entity);

            return errors;
        }

        // Delete entity from persistance repository
        public virtual void Delete(TEntity entity)
        {
            if (entity == null)
                throw new ArgumentNullException("entity");

            persistor.Delete(entity);
        }

        /// Gets IQueryable which we use from the concrete
        /// implementation of repository to implement our 
        /// query methods (FindBy).
        protected IQueryable<TEntity> Query()
        {
            return persistor.Query();
        }
    }

The Book Store Model –Entities and Approvals

At this point I’ll define the book store model, its entities, and approval objects.

The Book object has along with title, publisher info, ISBN also a list of one or many authors.


    public class Book : EntityBase<int>
    {
        public Book() : base() 
        {
            this.Authors = new List<Author>();
        }
        public Book(int id) : this() { Id = id; }
        public override ApprovalBase Approval { get; set; }

        public virtual string Title { get; set; }
        public virtual string Publisher { get; set; }
        public virtual string ISBN { get; set; }

        public virtual IList<Author> Authors { get; private set; }
    }

An Author have a name and also eventually takes part on writing several books.


    public class Author : EntityBase<int>
    {
        public Author() : base() 
        {
            this.Books = new List<Book>();
        }
        public Author(int id) : this() { Id = id; }
        public override ApprovalBase Approval { get; set; }

        public virtual string Name { get; set; }
        public virtual IList<Book> Books { get; private set; }
    }

Please note that the properties of the entities are marked as “virtual” as it is required by NHibernate.

How let’s create some approval services. Again – we can switch the approval the entity has even at run time as we have property injection implemented in our entities and they don’t depend on concrete approval services. If we set the approval of the entity to null, the validation will be successful regardless the data the entity contains.

To check if Book object contains valid data we implement BookApproval. A Book should have title and at least one author.


    public class BookApproval : ApprovalBase
    {
        public override IList<String> Validate<TEntity>(TEntity entity)
        {
            List<String> errors = new List<String>();
            Book book = entity as Book;

            if (book == null)
                throw new ArgumentException("Entity not a book");

            if (String.IsNullOrEmpty(book.Title))
                errors.Add("Title can not be empty");

            if ((book.Authors == null) || (book.Authors.Count == 0))
                errors.Add("A book should have at least one author");

            return errors;
        }
    }

To check if Author object contains valid data we implement AuthorApproval. An Author should have name.


    public class AuthorApproval : ApprovalBase
    {
        public override IList<String> Validate<TEntity>(TEntity entity)
        {
            List<String> errors = new List<String>();
            Author author = entity as Author;

            if (author == null)
                throw new ArgumentException("Entity is not an author");

            if (String.IsNullOrEmpty(author.Name))
                errors.Add("Name can not be empty");

            return errors;
        }
    }

Okay, sometimes they are some “no name” authors. If you think so, you still can create your own implementation of AuthorApproval service :-)

The Book Store Model – Repositories and Finders

First we define interfaces which the client code will use when talking to the book store repositories.

The IBookFinder states that we should have one new method, not required by IFinder, and this is ByISBN().
The IBookRepository exposes Find property of type IBookRepository.


    public interface IBookFinder : IFinder<Book, int> 
    {
        Book ByISBN(string ISBN); // adds new find methiod
    }
    public interface IBookRepository : IRepository<Book, int> 
    { 
        IBookFinder Find { get; }
    }

Similarly the same way for the Author:


    public interface IAuthorFinder : IFinder<Author, int> 
    {
        Author ByName(string name);
    }
    public interface IAuthorRepository : IRepository<Author, int>
    { 
        IAuthorFinder Find { get; } 
    }

Then we create concrete BookFinder and BookRepository


    public class BookFinder : FinderBase<Book, int>, IBookFinder
    {
        public override Book ById(int id)
        {
            return DataSource.Where(b => b.Id == id).FirstOrDefault();
        }
        public Book ByISBN(string ISBN)
        {
            return DataSource.Where(b => b.ISBN == ISBN).FirstOrDefault();
        }
    }

    public class BookRepository : RepositoryBase<Book, int>, IBookRepository
    {
        public BookRepository(
            IPersistor<Book, int> persistor,
            IBookFinder entityFinder)
            : base(persistor, entityFinder) { }

        public IBookFinder Find
        {
            get { return (IBookFinder)Finder; }
        }
    }

and also concrete AuthorFinder and AuthorRepository


    public class AuthorFinder : FinderBase<Author, int>, IAuthorFinder
    {
        public override Author ById(int id)
        {
            return DataSource.Where(a => a.Id == id).FirstOrDefault();
        }
        public Author ByName(string name)
        {
            return DataSource.Where(a => a.Name == name).FirstOrDefault();
        }
    }

    public class AuthorRepository : RepositoryBase<Author, int>, IAuthorRepository
    {
        public AuthorRepository(
            IPersistor<Author, int> persistor,
            IAuthorFinder finder)
            : base(persistor, finder) { }

        public IAuthorFinder Find
        {
            get { return (IAuthorFinder)Finder; }
        }
    }

The Book Store Model – External Dependencies

Until now we have a model for our book store. This model is fully testable and we can test how it works and inject some stubs for finders, approvals, etc. if it is needed. Here we go further and finish our work as we implement the rest of the book store with some dependencies to external projects. We will use NHibernate as ORM and furthermore FluentNHibernate. We will use StructureMap for inversion of control. We will need few ADO.NET drivers for different databases, as we will be able to switch between them on demand. At the end we will create in memory SQLite database and test our book store..

Download and unpack these files and add references from the solution explorer:

Download: fluentnhibernate-binary-1.0.0.595.zip from http://fluentnhibernate.org/
Referenced assemblies: Antlr3.Runtime.dll, Castle.Core.dll, Castle.DynamicProxy2.dll, FluentNHibernate.dll, Iesi.Collections.dll, NHibernate.dll, NHibernate.ByteCode.Castle.dll

Download: NHibernate.Linq-1.0.0.GA-bin.zip from http://sourceforge.net/projects/nhibernate/files/
Referenced assemblies: NHibernate.Linq.dll

Download: SQLite-1.0.65.0-binaries.zip from http://sqlite.phxsoftware.com
Referenced assemblies: System.Data.SQLite.DLL, System.Data.SQLite.Linq.dll

Download: Npgsql2.0.7-bin-ms.net3.5sp1.zip from http://npgsql.projects.postgresql.org/
Referenced assemblies: Npgsql.dll, Mono.Security.dll

Download: StructureMap_2.5.3.zip from http://structuremap.sourceforge.net/Default.htm
Referenced assemblies: StructureMap.dll

Download: xunit-1.5.zip from http://www.codeplex.com/xunit
Referenced assemblies: xunit.dll, xunit.extensions.dll

Place the following “using” directives at the beginning of the code file:


using NHibernate;
using NHibernate.Cfg;
using NHibernate.Linq;
using NHibernate.Tool.hbm2ddl;
using FluentNHibernate.Mapping;
using FluentNHibernate.Cfg;
using FluentNHibernate.Cfg.Db;
using StructureMap;

The Book Store Model – FluentNHibernate mappings

From the “Getting started” wiki page of the of the Fluent NHibernate project:
“Fluent NHibernate offers an alternative to NHibernate's standard XML mapping files. Rather than writing XML documents (.hbm.xml files), Fluent NHibernate lets you write mappings in strongly typed C# code. This allows for easy refactoring, improved readability and more concise code“.

We create dedicated classes to map the book store entity objects to tables into the database. For the entity’s identity NHibernate will automatically create automatically generated (auto incremented) values. The mapper class derive from FluentNHibernate.Mapping .ClassMap


    public sealed class BooksMap : ClassMap<Book>
    {
        public BooksMap()
        {
            Id(x => x.Id);
            Map(x => x.Title).Length(256).Default("").Not.Nullable();
            Map(x => x.Publisher).Length(256).Default("").Nullable();
            Map(x => x.ISBN).Length(16).Default("").Not.Nullable();
            HasManyToMany(x => x.Authors).LazyLoad();
        }
    }
    public sealed class AuthorsMap : ClassMap<Author>
    {
        public AuthorsMap()
        {
            Id(x => x.Id);
            Map(x => x.Name).Length(128).Default("").Not.Nullable();
            HasManyToMany(x => x.Books).LazyLoad();
        }
    }

The Book Store Model –NHibernate Persistors

As we defined concrete repositories and finders for the book and author entities, still we don’t have concrete persistors. First we define base persistor which depends on NHibernate (uses NHibernate.ISession, etc). Then we define the persistors for our entities.


    // Concrete NHibernate based persistance repository.
    public abstract class PersistorBase<TEntity, TIdentity>
        : IPersistor<TEntity, TIdentity>
    {
        protected ISession Session { get; set; }

        public PersistorBase(ISession session)
        {
            Session = session;
        }

        public TEntity Get(TIdentity id)
        {
            return (TEntity)Session.Get(typeof(TEntity), id);
        }

        public void Save(TEntity entity)
        {
            Session.SaveOrUpdate(entity);
        }

        public void Delete(TEntity entity)
        {
            Session.Delete(entity);
        }

        public IQueryable<TEntity> Query()
        {
            var qry = from t in Session.Linq<TEntity>()
                      select t;

            return qry.AsQueryable();
        }
    }

    // Persistance repository for books.
    public class BookPersistor : PersistorBase<Book, int>
    {
        public BookPersistor(ISession session) : base(session) { }
    }

    // Persistance repository for authors.
    public class AuthorPersistor : PersistorBase<Author, int>
    {
        public AuthorPersistor(ISession session) : base(session) { }
    }

The Book Store Model –NHibernate initialization

How comes stuff completely related to NHibernate and not directly to the book store model.

BaseDatabase is wrapper class for NHibernate initialization - a class from which concrete per database driver/server implementations will be created.

From this one we create implementation for Postgres, for MySQL, for SQLite, etc.
Into the concrete implementations we switch drivers, connection string, etc.

In Init() we open connection to the database.
The BuildSchema() method creates the database tables, relations, etc.


    public abstract class BaseDatabase : IDisposable
    {
        protected static Configuration configuration;
        protected static ISessionFactory sessionFactory;

        public ISession Session { get; protected set; }

        /// Does initialization, run from the constructors of the inherited classes.
        protected void Init()
        {
            sessionFactory = CreateSessionFactory();
            Session = sessionFactory.OpenSession();
            BuildSchema(Session);
        }

        protected abstract ISessionFactory CreateSessionFactory();

        private static void BuildSchema(ISession session)
        {
            SchemaExport schemaExport = new SchemaExport(configuration);
            schemaExport.Execute(true, true, false, session.Connection, null);
        }

        public void Dispose()
        {
            Session.Dispose();
        }

    }

And now I implement some concrete initializations per database driver/server:


    /// Database configured as in file SQLite database.
    public class SQLiteInFileDatabase : BaseDatabase
    {
        public string FileName { get; private set; }

        /// Create SQLite database with specified file name.
        public SQLiteInFileDatabase(string fileName)
        {
            // file name to store the database, "database.db" for example.
            FileName = fileName;

            // does not run the base constructor, but calls Init() by itself.
            Init(); 
        }

        protected override ISessionFactory CreateSessionFactory()
        {
            return Fluently.Configure()
                .Database(SQLiteConfiguration.Standard.UsingFile(FileName).ShowSql())
                .Mappings(m => m.FluentMappings.AddFromAssemblyOf<BooksMap>())
                .ExposeConfiguration(Cfg => configuration = Cfg)
                .BuildSessionFactory();
        }
    }

    /// Database configured as in memory SQLite database.
    public class SQLiteInMemoryDatabase : BaseDatabase
    {
        /// Create in memory SQLite database.
        public SQLiteInMemoryDatabase()
        {
            Init();
        }

        protected override ISessionFactory CreateSessionFactory()
        {
            return Fluently.Configure()
                .Database(SQLiteConfiguration.Standard.InMemory().ShowSql())
                .Mappings(m => m.FluentMappings.AddFromAssemblyOf<BooksMap>())
                .ExposeConfiguration(Cfg => configuration = Cfg)
                .BuildSessionFactory();
        }
    }


    /// Database configured as in memory SQLite database.
    public class PostgresDatabase : BaseDatabase
    {
        public string ConnectionString { get; private set; }

        /// Create in memory SQLite database.
        public PostgresDatabase(string connectionString)
        {
            ConnectionString = connectionString;
            Init();
        }

        protected override ISessionFactory CreateSessionFactory()
        {
            return Fluently.Configure()
                .Database(PostgreSQLConfiguration.PostgreSQL81
                    .ConnectionString(ConnectionString).ShowSql())
                .Mappings(m => m.FluentMappings.AddFromAssemblyOf<BooksMap>())
                .ExposeConfiguration(Cfg => configuration = Cfg)
                .BuildSessionFactory();
        }
    }

The Book Store Model – the BookStore database class

It is time for the book store class. The BookStore class contains book and author repository and does the necessary initialization of those. Also contains concrete instance of BaseDatabase. We inject concrete instance of BaseDatabase from the parameterized constructor. We also have parameter less constructor which leans upon StructureMap to init this singleton class with concrete instance and implementation of BaseDatabase.


    /// Is a singleton, use GetInstance()
    public class BookStore
    {
        private static BookStore bookStore;

        public static BookStore GetInstance()
        {
            if (bookStore == null)
                bookStore = new BookStore();
            return bookStore;
        }

        private BaseDatabase db;
        public IBookRepository BookRepository { get; private set; }
        public IAuthorRepository AuthorRepository { get; private set; }


        /// Inject concrete instance of BaseDatabase.
        public BookStore()
            : this(ObjectFactory.GetInstance<BaseDatabase>())
        { }

        public BookStore(BaseDatabase db)
        {
            this.db = db;
            Init();
        }


        private void Init()
        {
            IBookFinder bookFinder = new BookFinder();
            BookPersistor bookPersistor = new BookPersistor(db.Session);
            BookRepository = new BookRepository(bookPersistor, bookFinder);


            IAuthorFinder authorFinder = new AuthorFinder();
            AuthorPersistor authorPersistor = new AuthorPersistor(db.Session);
            AuthorRepository = new AuthorRepository(authorPersistor, authorFinder);
        }

        // can be used to implement the Unit of Work Pattern.
        public void Flush()
        {
            db.Session.Flush();
        }
    }

The Book Store Model – Usage

For the usage and to run the final example I’ll put the rest into the Program.cs file.

First I create two concrete implementation of BaseDatabase: SQLite where we have specified file name for our SQLite database and Postgres where we have specified the concrete connection string.

Then we have method ConfigureDependencies() to initialize StructureMap. We say which concrete class to be created whenever we create instance of BaseDatabase using the default parameter less constructor. Please note that we have such situation in class BookStore in GetInstance() where it creates an instance of itself. BookStore depends only on BaseDatabase class, but not on the concrete implementations of BaseDatabase. Then StructureMap will decide for the concrete implementation of BaseDatabase.


    public class Program
    {
        public class SQLiteInFileConcreteDatabase : SQLiteInFileDatabase
        {
            public SQLiteInFileConcreteDatabase() : base("test.db") { }
        }

        public class PostgresConcreteDatabase : PostgresDatabase
        {
            public PostgresConcreteDatabase()
                : base("Server=127.0.0.1;Port=5432;Database=bookstore;User Id=postgres;Password=;")
            { }
        }

        /// <summary>
        /// Configure StructureMap dependencies.
        /// </summary>
        private static void ConfigureDependencies()
        {
            ObjectFactory.Initialize(x =>
            {
                x.ForRequestedType<BaseDatabase>()
                    .TheDefaultIsConcreteType<SQLiteInMemoryDatabase>();
                    // .TheDefaultIsConcreteType<SQLiteInFileDatabaseConcrete>();
                    // .TheDefaultIsConcreteType<PostgresConcreteDatabase>();
                    // whatever concrete database and settings
            });
        }



        static void Main(string[] args)
        {
            ConfigureDependencies();

            BookStore bookStore = BookStore.GetInstance();

            Author JohnDoe = new Author() { Name = "John Doe" };
            bookStore.AuthorRepository.Save(JohnDoe);

            Author JaneDoe = new Author() { Name = "Jane Doe" };
            bookStore.AuthorRepository.Save(JaneDoe);

            Book book;

            // test approval:
            book = new Book() { };
            book.Approval = new BookApproval();
            Console.WriteLine("Approval of book: {0}", String.Join(System.Environment.NewLine, book.Validate().ToArray()));


            // test saving to database
            book = new Book() { Title = "Meet John Doe", ISBN = "1234567890123" };
            book.Authors.Add(JohnDoe);
            book.Authors.Add(JaneDoe);
            bookStore.BookRepository.Save(book); 
            bookStore.Flush(); // moan on error

            Book selected = bookStore.BookRepository.Find.ByISBN("1234567890123");
            Console.WriteLine(String.Format("Author one: {0}", selected.Authors[0].Name));
            Console.WriteLine(String.Format("Author two: {0}", selected.Authors[1].Name));
            Console.ReadLine();
        }
    }

When I ran the program, I’ve got the following output:

I also gave a try of the BookApproval. The validation has failed with two error messages. Saving that book definition – with bookStore.BookRepository.Save(book); - wouldn’t be possible as the validation did not pass.

At the end I place some links related to the theme.

An excellent blog on implementing repository and finder pattern:
http://russelleast.wordpress.com/2008/09/20/implementing-the-repository-and-finder-patterns/

Part 2 from the Blog attending the MVC Storefront Project where the Repository Pattern is used:
http://blog.wekeroad.com/mvc-storefront/asp-net-mvc-mvc-storefront-part-2/

Fluent mapping for NHibernate
http://fluentnhibernate.org/

To download NHibernate.Linq
http://sourceforge.net/projects/nhibernate/files/

ADO.NET SQLite Data Provider:
http://sqlite.phxsoftware.com

ADO.NET Postgresql Data Provider:
http://npgsql.projects.postgresql.org/

StructureMap Inversion of Control Framework:
http://structuremap.sourceforge.net/Default.htm

Atanas Hristov

Design Patterns – Memento Pattern

2009-12-01T08:08:00.000-08:00

The Memento Pattern is useful to remember the state of object without keeping copy of the whole object. Copying of the entire object is sometimes inefficient as the copy eventually contains much more information that we need to restore back.

Memento

Memento is the object that can remember the internal state of another object.


// Memento. Uses deep copy and serialization
// to save/restore the state of type TState.
public class Memento<TState>
{
  MemoryStream stream = new MemoryStream();
  BinaryFormatter formatter = new BinaryFormatter();

  public Memento<TState> Save(TState state)
  {
    formatter.Serialize(stream, state);
    return this;
  }

  public TState Restore()
  {
    stream.Seek(0, SeekOrigin.Begin);
    TState state = (TState)formatter.Deserialize(stream);
    stream.Close();
    return state;
  }
}

The Memento in this example uses generics to ensure type consistence and prevent using type conversion.

Originator

Originator is the object which state to remember and restore back if needed. The Originator has two methods for that:
- GetMemento() that returns the state of the object
- and SetMemento() receives back state to restore from


// The Originator has one property that returns 
// the complete state of the object.
public interface IOriginator<TState>
{
  TState State { get; }
}

// Holds the state of the Originator
[Serializable]
public class ProductState
{
  public string Name { get; set; }
  public float Price { get; set; }
}

// Originator
// The complete state is moved to one property 
// to generalize the memento pattern.
[Serializable]
public class Product : IOriginator<ProductState>
{
  public Product()
  {
    this.State = new ProductState();
  }

  public Product(string name, float price)
    : this()
  {
    this.State.Name = name;
    this.State.Price = price;
  }

  public ProductState State { get; private set; }

  public Memento<ProductState> GetMemento()
  {
    return new Memento<ProductState>().Save(State);
  }

  public void SetMemento(Memento<ProductState> memento)
  {
    State = memento.Restore();
  }

  public override string ToString()
  {
    return String.Format(System.Globalization.CultureInfo.InvariantCulture,
      "{0} {1:f2}", State.Name, State.Price);
  }
}

Caretaker

Caretaker is the object that controls when to create Memento but the Originator will use the stored into the Caretaker state to restore from.


// Usage example and Caretaker as the same time.
static void Main(string[] args)
{
  // Caretaker is in this example the class that holds the Main() void
  // or the Main() void itself of you want.
  Memento<ProductState> memento = new Memento<ProductState>();

  Product product = new Product("Name one", 100f);
  Console.WriteLine("Initial state: " + product.ToString());

  memento = product.GetMemento();
  Console.WriteLine("The state was saved to memento");

  // Change the state of the Originator
  product.State.Name = "Name two";
  product.State.Price = 200f;
  Console.WriteLine("State changed: " + product.ToString());

  // Change the state of the Originator
  product.State.Name = "Name three";
  product.State.Price = 300f;
  Console.WriteLine("State changed: " + product.ToString());

  product.SetMemento(memento);
  Console.WriteLine("The state restored from memento");

  Console.WriteLine("Reverted state: " + product.ToString());

  Console.ReadLine();
}

which gives after running the following output:

The Memento is save-state undo command, where the captured is a backup. In this example the Memento object used in-memory storage to keep backup of state, but the Memento object could also even persist state into a database.

Atanas Hristov

AJAX publish/subscribe

2009-10-31T09:40:00.000-07:00

Calling long running web server process and locking the user for a while in web applications with the typical for the HTTP request/replay way can be critical for the user expirience. Even more, possibly we don't get back the data due to problems with the network connection or browser timeouts.

Even if on top of unreliable protocol like HTTP we can provide some abstraction level to ensure we'll get the result from the web server. We could simulate the publish/subscribe pattern in ajax. Furthermore our communication with the web server is asynchronous and allows our application to respond better to the user interactions.

On the web server we could implement multithreading and open working threads which get the calculations done.

With javascript we send request to the web server and then in some interval of time we again and again ask if the server has prepared the result. When the web server has collected the information we need, we take the data from the web server, display on the page and stop the repetative calls to the web server.

I will implement publish/subscribe with ASP.NET MVC and jQuery.

The CityWeather model

First i'll create model class CityWeather. The only public properties of CityWeather object are "City" and "Temperature".

After CityWeather class created, the constructor calls Measure() in thread. The Measure() function simulates long running process used to collect the weather information for that city.

We store all the requests for measurements in static collection _measurements. The keys of this collection are the city names.

The only public function of the model class is the static function GetCityWeather() which when called will check if in _measurements exists object CityWeather for this city. If not will create one. The function returns back the corresponding CityWeather object from the _measurements collection.



 namespace PublishSubscribe.Models
 {
  // Measurements per city.
  // Call class method CityWeather.GetCityWeather(city) 
  // to get CityWeather object with measurements 
  // for that city. 
  // Repead calling CityWeather.GetCityWeather(city) 
  // until city.Temperature is not null.
  public class CityWeather
  {
   // Holds all requested measurements.
   // Used from class method GetCityWeather()
   // The keys are city names.
   // The values are CityWeather objects.
   private static Dictionary<string, CityWeather> _measurements = 
    new Dictionary<string, CityWeather>();

   // public properties of CityWeather object:
   public string City { get; private set; }
   public int? Temperature { get; private set; }


   // The constructor itself starts measurement 
   // in an asynchronous thread.
   private CityWeather(string city) 
   {
    this.City = city;

    // after the object is constructed will start 
    // doing measurement in a thread, which respectively 
    // takes some time
    ThreadStart ts = new ThreadStart(Measure);
    Thread th = new Thread(ts);
    th.Priority = ThreadPriority.Lowest;
    th.Start();
   }

   // Worker method started in separate thread from 
   // the constructor
   private void Measure()
   { 
    // measurement takes some time - up to a minute
    Thread.Sleep(new Random().Next(1,6) * 10000);

    // lock the object alowing concurent access
    // to the object properties
    lock (this)
     // degrees Celsius between 10 and 20
     Temperature = new Random().Next(10, 20);
   }


   // The only public method that capsulates all the logic 
   // of keeping single instances - one per city - 
   // just as static memory for the purpose of the
   // demonstration.
   //
   // Keep calling CityWeather.GetCityWeather(city) until 
   // you get back an CityWeather object with 
   // property Temperature which is not null.
   public static CityWeather GetCityWeather(string city)
   {
    lock (_measurements)
    {
     if (! _measurements.ContainsKey(city))
     {
      CityWeather cw = new CityWeather(city);
      _measurements.Add(city, cw);
     }

     return _measurements[city]; // check 
    }
   }
  }
 }

The usage of this class is pretty simple. We call the static function CityWeather.GetCityWeather() with the name of a city to get weather measurements for that city. We repeat the call again and again until we get back CityWeather object where Temperature property is set - is not null, but contains value.

The Weather controller

Then I'll create the controller class:



 namespace PublishSubscribe.Controllers
 {
  public class WeatherController : Controller
  {
   public JsonResult Measure(string city)
   {
    return Json(Models.CityWeather.GetCityWeather(city));
   }

   public ActionResult Index()
   {
    return View();
   }
  }
 }

The controller has two methods. Measure gets weather measurements for one given city. We send back JSON result.

The Index method we will use to create page where we will demonstrate how the AJAX publish/subscribe calls will work.

We are ready to try how the Measure JSON handler will respond and to see the how the CityWeather model will work. We run the application and navigate to /weather/measure where we request measurements for a city and repetative hit repoad on the browser until we receive back the Temperature calculated.

Here is how example session with repetative calls looks like:



 URL: http://localhost:3284/weather/measure/?city=berlin
 Response: {"City":"berlin","Temperature":null}
 ...
 URL: http://localhost:3284/weather/measure/?city=berlin
 Response: {"City":"berlin","Temperature":null}
 ...
 URL: http://localhost:3284/weather/measure/?city=berlin
 Response: {"City":"berlin","Temperature":12}

AJAX publish/subscribe with jQuery

Now I'm going to implement the web page to demonstrate the idea behind the AJAX publish/subscribe.

The html body tag is very simple.



 <body>

 <label for="city">City:</label>
 <input type="text" id="txtCity" />
 <input type="button" value="measure" id="btnMeasure" />

 <table id="cites">
  <thead>
   <tr><td style="width:200px">City</td><td>Temperature</td></tr>
  </thead>
  <tbody>
  </tbody>
 </table>

 </body>

We write city name into the input box and click the "measure" button. We repeat that several times with other city names. We expect whenever the server has measured the weather for a city we asked for, the result will be added to the table as new row. The order of the cities we ask for measurements is not necessarily the order we'll get back calculated measurements. The time the server will spend to take weather measurements may vary from city to city and is not presumable.

This way we will have asynchronious communication with the server and the user will appreciate the better respond from the application.

Last, I'll put some javascript after the closing body task and will automate the html page with jQuery.

As we don't have multithreading in javascript we simulate it with setInterval and clearInterval. We start repetative calls as we run sendMeasureRequest(city) every second and ask the web server if the measurements for that city are calculated. Once the server gives back calculated results we stop the repetative calls.

The setInterval() function gives us interval ID which we later use at calling clearInterval() to stop repetative tasks. Then we also need to map somewhere interval ID to city name, thereof we create array measurements which keys are city names. The values of the measurements dictionary are data structures wich hold interval ID, city name and the temperature as measured from the web server.

Once the web server respond calculated measurement we stop the corresponding repetative calls to the web server and call the function cityMeasured(). We add new row into the table with the measurements.



 <script type="text/javascript">

  /* Hash array of all collected measurememts */
  var measurements = new Array();

  /* Does weather measurement for a city */
  function measureCity(city) {
   if (measurements[city] == undefined) {
    // send request to the server every one second
    var intervalID = setInterval(sendMeasureRequest, 1000, city);
    measurements[city] = {
     IntervalID: intervalID,
     City: city,
     Temperature: null
    };
    sendMeasureRequest(city);
   }
   cityMeasured(city);
  }
  
  /* Send GET request to the server to collect weather measurements for a city */
  function sendMeasureRequest(city) {
   $.ajax({
    'url': '<%= Url.Action("Measure") %>',
    'type': 'GET',
    'dataType': 'json',
    'data': { 'city': city },
    'success': function(data) {
     if (data.Temperature != null) {
      clearInterval(measurements[data.City].IntervalID);
      measurements[data.City].Temperature = data.Temperature;
      cityMeasured(data.City);
     }
    }
   });
  }

  /* Does weather measurement for a city */
  function cityMeasured(city) {
   if (measurements[city].Temperature != null) {
    if ($('#tr_' + city).length == 0) {
     $("#cites > tbody").append('<tr id="tr_' + city + '"><td>'
      + measurements[city].City
      + '</td><td>'
      + measurements[city].Temperature + ' grad'
      + '</td></tr>');
    }
   }
   $('#tr_' + city).fadeOut();
   $('#tr_' + city).fadeIn();
  }
   
  /* SetUp click handler */
  $(document).ready(function() {
   $("#btnMeasure").click(function() {
    var city = $("#txtCity").val();
    measureCity(city);
   });
  });
 </script>

After I ran the application and navigated to /weather/ I asked for weather measurements for the following cities in the exact order: Paris, Boston, Rom, Hamburg

Then I waited few seconds and the weather measurements were displayed to the page one after other:

Well, we may consider as next to be done, once the weather in city from the table has charnged, we refresh the information on the table.

Atanas Hristov

Design Patterns – Abstract Factory Pattern

2009-10-13T05:39:00.000-07:00

Factories are objects that encapsulate the logic for creating other objects.

Factory object could create one or another object based on some configuration parameters. Or the factory could decide what kind of concrete object to create based on a parameter to some object creational method. For example if the method received post-code the factory creates City object and when the parameter is an email address the factory creates Customer object. In that way one might create factory to select one or another kind of object from database based on the user input.

Abstract Factory

The Abstract Factory is that encapsulates the way of creating concrete objects that have lot of common.

Often the created from abstract factory objects derive from same base class or share some interface. Abstract factory object for example could be used to create fake objects for the purpose of testing the software, and create regular objects otherwise in production mode. The fake object and the regular object derive from same base class or share same interface. The client code deals only with instances of the base type and has no knowledge of the concrete implementation.

I will give an example of abstract factory created with C#.

Reflection based abstract factory

The central feature of our abstract factory is to create concrete objects based on key/value pairs.

We register the types the factory is able to create into a dictionary. For registration of the types the factory may create we expose method Register().

Our base abstract factory class uses reflection to call the object constructors of the concrete type. That is done in method CreateInstance(). We invoke CreateInstance() with:

key - that will be used to create one concrete object or another as it is registered already via Register().

typeParams - if the concrete object has parameterized constructor which we want to use, then we specify the parameter types in an array.

valParams - if the concrete object has parameterized constructor which we want to use, then we specify the parameter values in an array.

Following is a implementation of reflection based abstract factory:



    // T1 is the appropriate key type.
    // T2 is the base type from which derive all the types the factory can create.
    public abstract class AbstractFactory<T1, T2>
    {
        // Creates the factory.
        // T1 is the appropriate type. 
        // T2 is the base type from which derive all the types the factory can create.
        public static AbstractFactory<T1, T2> CreateFactory()
        {
            throw new Exception("Override FactoryReflected.CreateFactory()!");
        }

        // Register for types the factory can create.
        protected Dictionary<T1, Type> _registered = new Dictionary<T1, Type>();

        // Registers the specified factory types.
        protected void Register(T1 key, Type type)
        {
            _registered.Add(key, type);
        }


        // Creates new instance of type by enumeration key. 
        public T2 CreateInstance(T1 key, Type[] typeParams, object[] valParams)
        {
            Type type = _registered[key];

            System.Reflection.ConstructorInfo cInfo =
                type.GetConstructor(typeParams);

            return (T2)cInfo.Invoke(valParams);
        }

    }

We also have used generics to make the implementation of reflection based abstract factory more generalized.

Personal name

Let's face the problem and how we are going to find a solution. The different societies have different conventions for personal full name. In Russia the common order is "family-name given-name". In some situations the family-name is capitalized. In west Europe the usual convention is "given-name family-name", etc.

Our problem is - we are going to use the appropriate form of address when we communicate with people from different regions. For simplicity assume we have the family and the given name. We need a way to compose appropriate full name.

First we have the base class Name. The Name class has first and last name properties. We also have an abstract method GetFullName() which should give different result for different society. Furthermore, the concrete implementation will be done in derived classes:



    // Base abstract class from which concrete implementations derive
    public abstract class Name
    { // see http://en.wikipedia.org/wiki/Full_name#Naming_convention

        protected string firstName;
        protected string lastName;
        protected Name() { }
        public Name(string first, string last)
        {
            this.firstName = first;
            this.lastName = last;
        }

        // Full name can be composed differently 
        // as the different societies have they different 
        // naming conventions
        public abstract string GetFullName();
    }

    // composing Western full name
    public class WesternName : Name
    {
        public WesternName(string first, string last) : base(first, last) { }
        public override string GetFullName() { return firstName + " " + lastName; }
    }

    // composing Eastern full name
    public class EasternName : Name
    {
        public EasternName(string first, string last) : base(first, last) { }
        public override string GetFullName() { return lastName + " " + firstName; }
    }

    // another Eastern full name convention
    public class EasternOfficialName : Name
    {
        public EasternOfficialName(string first, string last) : base(first, last) { }
        public override string GetFullName() { return lastName.ToUpper() + " " + firstName; }
    }

Concrete factory

Having the abstract factory from above we create concrete factory used for creation of objects of classes derived from the Name class. The NameFactory contains the initialization of itself in method CreateFactory(). If we create new concrete class derived from class Name to fit another convention for personal full name then we also have to register that new class in CreateFactory() method.



    public class NameFactory : AbstractFactory<string, Name>
    {
        private NameFactory() { }

        public static new NameFactory CreateFactory()
        {
            NameFactory factory = new NameFactory();

            // Register which concrete type to create for which key
            factory.Register("WesternOrder", typeof(WesternName));
            factory.Register("EasternOrder", typeof(EasternName));
            factory.Register("EasternOfficialOrder", typeof(EasternOfficialName));

            return factory;
        }
    }

We will create instances of NameFactory only via the static method CreateFactory() and thereof we have specified the default constructor to be private.

Using the concrete factory

We create nameFactory object and then call one after another GetFullName() of all possible derived from class Name objects. These derived from Name objects we create as we call method CreateInstance() of nameFactory.



    class Program
    {
        static void Main(string[] args)
        {
            NameFactory nameFactory = NameFactory.CreateFactory();

            foreach (string convention in new string[] { 
                "WesternOrder", "EasternOrder", "EasternOfficialOrder", })
            {
                Name name = nameFactory.CreateInstance(convention,
                    new Type[] { typeof(string), typeof(string) },
                    new object[] { "Atanas", "Hristov" });

                Console.WriteLine(name.GetFullName());
            }


            Console.Read();
        }
    }

And finally the output to the console:

Atanas Hristov

Design Patterns – Singleton Pattern

2009-09-25T05:24:00.000-07:00

The Singleton pattern gives us a way to restrict the instantiation of objects of given class to certain number, in the common usage to one only.

The Singleton class instantiates itself and works as a global repository for an instance of itself. For example we share a database connection or log writer across all threads in one process.

Implementation of Singleton pattern

Here i'm going to implement Singleton class in C#. The class should hide its constructor. It has also GetInstance() method that gives back the only concrete instance. We embed the concrete instance of the class into the static variable "obj".

For the purpose of the demonstration we have one public method Add() used to add some number to the class and Total() which gives back the total of the added numbers.



    public class Singleton
    {
        private static Singleton obj = new Singleton(); // holds a reference to the only concrete instance

        private static int total = 0; // we add numbers up to this via Add()

        private Singleton() { } // hiden constructor

        public static Singleton GetInstance() { return obj; } // returns the only concrete instance

        public void Add(int number)
        { // add up to the total
            lock (obj) // synchronize in concurrency
            {
                Thread.Sleep(new Random().Next(1000)); // randomly wait up to a second
                total += number;
                Console.WriteLine(String.Format("Add {0} to total", number));
            }
        }

        public int Total()
        { // gets the total
            lock (obj)
                return total;
        }
    }

In Add() method we have a timeout up to a second to randomize the time to run the method.

We also locked the access to the class variables for concurrency. We are going to test the Singletion class in multithreaded environment.

Usage of Singleton pattern

First we create three static helper methods which will make calls to Add() with different number from one to three.



    class Program
    {
        // add
        static void HelperOne() { Singleton.GetInstance().Add(1); }
        static void HelperTwo() { Singleton.GetInstance().Add(2); }
        static void HelperThree() { Singleton.GetInstance().Add(3); }
...

Then in Main() we run three threads and run concurrently the three static helper methods.

We wait for the threads to finish and show the total of all additions to the singleton class.



        static void Main(string[] args)
        {
            Thread[] threads = new Thread[]
            {
                new Thread(new ThreadStart(HelperOne)),
                new Thread(new ThreadStart(HelperTwo)),
                new Thread(new ThreadStart(HelperThree))
            };

            foreach (Thread thread in threads) { thread.Start(); }
            foreach (Thread thread in threads) { thread.Join(); }

            Console.WriteLine(String.Format("The total is {0}",
                Singleton.GetInstance().Total()));

            Console.Read();

        }

Run the example

Running that I've got the following output:

Happy codding!

Atanas Hristov

Design Patterns – Chain of Responsibility Pattern

2009-09-11T09:16:00.001-07:00

Imagine you have complicated decision logic and you’ve got a big if-then-else like structure in your code which you want to simplify.
The Chain of Responsibility Pattern is a good way for code refactoring in such situation. It will make the code more flexible and easy to support and modify in the future.

You prepare a set of interdependent chain handler classes linked in a chain. Every chain handler class implements part of the decision logic and has a link to next chain handler object. A request data object is passed thru the chain. Eventually one of the handlers on the chain matches some decision criteria, does data processing and ends up the run flow. This would be the handler objects in the chain that takes the responsibility and does data processing having received the request data object.

In this example we will try to programmatically come up with a conclusion based on passed in to the chain two boolean parameters. For every possible combination of those parameters we are going give a conclusion back, so we have four different possible results. Otherwise we could do things using conditional structures like:



If Param1 is true
        If Param2 is true
                Conclusion1
        Else
                Conclusion2
Else
        If Param2 is true
                Conclusion3
        Else
                Conclusion4

Based on that conditional structure we will create chain of responsibility with four different chain handler classes covering all decision making combinations.

We will use C# as a programming language for the examples.

Chain Handler Interface and Base Class

We start with the definition of the chain handler interface. The chain handler object stores internally a request data object. We have a way to set if there is a handler next on the chain. The handler has Run() void where the decision making and eventually data processing will be done.



    // All handler objects implement common interface.
    // T: request object- holds data to process 
    // and the result of the processing
    public interface IChainHandler<TRequest>
    {
        IChainHandler<TRequest> SetNextLink(IChainHandler<TRequest> next); // set link to next handler
        void Run(); // does processing
    }

As we will have four chain handler classes and they all have a lot in common, we create parent abstract base class for chain handler.



    // base class for all concrete chain handler objects
    public abstract class ChainHandlerBase : IChainHandler<RequestData>
    {
        // the request data object
        protected RequestData _requestData;

        // a reference to next chain handler object
        private IChainHandler<RequestData> _nextHandler;

        // hide parameterless constructor
        private ChainHandlerBase() { }

        // expose constructor with parameters
        public ChainHandlerBase(RequestData requestData)
        {
            _requestData = requestData;
        }
        // set the reference to the next chain handler object
        public IChainHandler<RequestData> SetNextLink(IChainHandler<RequestData> nextHandler)
        {
            _nextHandler = nextHandler;
            return _nextHandler;
        }

        // let the concrete implementation make processing decision 
        public abstract void Run();

        // run next handler in the chain if defined or end up the processing
        protected void RunNext()
        {
            if (_nextHandler != null)
                _nextHandler.Run();
        }

    }

Request Data Object

A step back – we need to define the request data object which we’ll pass thru the chain. This object holds two input boolean parameters and a holder where we write the conclusion message back.



    // Data to pass thru the chain.
    // Based on this data the chain 
    public class RequestData
    {
        // pass in parameters
        public bool HaveLotOfMoney { get; set; }
        public bool HaveBrilliantIdea { get; set; }

        // a message to send back
        public string MessageBack { get; set; }
    }

Concrete Chain Handler Implementations

Now we are ready to define concrete chain handler classes and cover all possible combinations of the input parameters.



    // concrete chain handler object
    public class ChainHandlerOne : ChainHandlerBase
    {
        public ChainHandlerOne(RequestData requestData) : base(requestData) { }
        public override void Run()
        {
            if ((_requestData.HaveLotOfMoney) && (_requestData.HaveBrilliantIdea))
            {
                _requestData.MessageBack = "I am with you.";
                return;
            }
            RunNext();
        }
    }

    // concrete chain handler object
    public class ChainHandlerTwo : ChainHandlerBase
    {
        public ChainHandlerTwo(RequestData requestData) : base(requestData) { }
        public override void Run()
        {
            if ((_requestData.HaveLotOfMoney) && (!_requestData.HaveBrilliantIdea))
            {
                _requestData.MessageBack = "Well done. Go on pension.";
                return;
            }
            RunNext();
        }
    }

    // concrete chain handler object
    public class ChainHandlerThree : ChainHandlerBase
    {
        public ChainHandlerThree(RequestData requestData) : base(requestData) { }
        public override void Run()
        {
            if ((!_requestData.HaveLotOfMoney) && (_requestData.HaveBrilliantIdea))
            {
                _requestData.MessageBack = "What a nice idea.";
                return;
            }
            RunNext();
        }
    }

    // concrete chain handler object
    public class ChainHandlerFour : ChainHandlerBase
    {
        public ChainHandlerFour(RequestData requestData) : base(requestData) { }
        public override void Run()
        {
            if ((!_requestData.HaveLotOfMoney) && (!_requestData.HaveBrilliantIdea))
            {
                _requestData.MessageBack = "Don't give up.";
                return;
            }
            RunNext();
        }
    }

Set Up the Chain

We are ready at this point to put in order the chain. We create chain handler objects and link them in a appropriate order. We send to the first handler in the chain a request data object and hit the Run() method to get the result calculated.



        // wraps the chain initialization and processing code
        static RequestData WhatAboutMe(RequestData requestData)
        {
            // construct the first chain handler.
            ChainHandlerBase firstHandler = new ChainHandlerOne(requestData);

            // arrange chain of responsibility as list of chain handker objects
            firstHandler
                .SetNextLink(new ChainHandlerTwo(requestData))
                .SetNextLink(new ChainHandlerThree(requestData))
                .SetNextLink(new ChainHandlerFour(requestData));

            // start processing of the request data
            firstHandler.Run();

            // return back the request data with the message created
            return requestData;
        }

Run the Chain

The win of utilizing chain responsibility pattern is the extensibility of our code in future. If we need additional logic we have to implement new chain handler class. We also may construct the chains in one or another way, we can order the chain handler object based on concrete needs. We absolutely take care of single responsibility principle and we divide a long and complicated to maintain code into well testable small classes.

Finally let’s run our chain of responsibility implementation. We’ll send every possible combination of input to the chain and see what’ll happen.



static void Main(string[] args)
{
  Console.WriteLine(WhatAboutMe(new RequestData {
    HaveLotOfMoney = true, HaveBrilliantIdea = true }).MessageBack);

  Console.WriteLine(WhatAboutMe(new RequestData {
    HaveLotOfMoney = true, HaveBrilliantIdea = false }).MessageBack);

  Console.WriteLine(WhatAboutMe(new RequestData { 
    HaveLotOfMoney = false, HaveBrilliantIdea = true }).MessageBack);

  Console.WriteLine(WhatAboutMe(new RequestData { 
    HaveLotOfMoney = false, HaveBrilliantIdea = false }).MessageBack);

  Console.Write("Hit Enter to finish.");
  Console.ReadLine();
}

Running that we get on the console like:

Atanas Hristov

Upload file to database with ASP.NET MVC and Castle Active Record

2009-09-07T04:02:00.001-07:00

A file upload function to web application raises the question where to store the uploaded data. One possibility is to just store into the file system. This is inexpensive and easy to implement, but you have to think for file backups. If you don’t have huge amount of data you can also upload files directly into a database using binary format for table column to store the content of the file.

In this post I’m going to give a try of the second option and create simple application to store uploaded files directly into the database.

I will use Postgres database to store the file uploads and as ORM I will use Active Record from the Castle project. Then I need a driver for .NET to connect to the database, we will use the Npgsql driver.

With Castle Active Record you can easy switch to another database server; it’s just matter of switching the referenced driver and replace appropriately the configuration into Web.config file.

Assume we have PostgreSQL Server on localhost up and running and we will connect to the database "postgres" as user "postgres".

Create the project and set the configuration

We start with creating new ASP.MVC Application in Visual Studio and give it the name of "UploadToDb".

We then add references to the following assemblies from our project:

NHibernate.dll
Castle.ActiveRecord.dll
Castle.Components.Validator.dll
Castle.Core.dll
Castle.DynamicProxy.dll
Iesi.Collections.dll
Npgsql.dll

We change the Web.config file and add the appropriate settings for Active Record.

In "configSections" we add new section sub element for the Active Record. Next to "configSections" we add "activerecord" element where we specify the connection parameters and the database driver we are going to use.



<configuration>
   <configSections>
      <section name="activerecord" type="Castle.ActiveRecord.Framework.Config.ActiveRecordSectionHandler, Castle.ActiveRecord" />
            ….
   </configSections>
   <activerecord isWeb="false" isDebug="true">
      <config>
         <add key="hibernate.connection.provider" value="NHibernate.Connection.DriverConnectionProvider"/>
         <add key="hibernate.dialect" value="NHibernate.Dialect.PostgreSQL81Dialect"/>
         <add key="hibernate.connection.driver_class" value="NHibernate.Driver.NpgsqlDriver"/>
         <add key="hibernate.connection.connection_string" value="Server=localhost;Port=5432;Database=postgres;User ID=postgres;Password=;"/>
 </config>
   </activerecord>

Database table and domain model

First we'll create Active Record class for the domain object "Upload" into Models directory. This is an entity object and has property Id which is a primary key into the database. We’ve got also data property which holds the binary data from the file we upload. There is also mimetype property which holds the MIME type of the uploaded file.



using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using Castle.ActiveRecord;
using Castle.ActiveRecord.Framework.Scopes;
using NHibernate.Expression;
using System.Data;
using System.Collections;

namespace UploadToDb.Models
{
    [ActiveRecord("uploads")]
    public class Upload : ActiveRecordBase<Upload>
    {
        private int id = 0;
        [PrimaryKey(PrimaryKeyType.Sequence, SequenceName = "uploads_seq")]
        public int Id
        {
            get { return id; }
            set { id = value; }
        }

        private byte[] data = new byte[] { };
        [Property]
        public byte[] Data
        {
            get { return data; }
            set { data = value; }
        }

        private string mimetype = "";
        [Property]
        public string Mimetype
        {
            get { return mimetype; }
            set { mimetype = value; }
        }

        public static Upload FindById(int id)
        {
            return FindOne(Expression.Eq("Id", id));
        }
    }
}

To search uploaded files into the database we use the above implemented method FindById(int) which is just used to enclose and wrap that extra Actie Record syntax with the expressions. Otherwise we have a lot of search capabilities coming with Active Record, for example to get list of all file uploads we use Models.Upload.FindAll() as the class Models.Upload inherits from ActiveRecordBase class.

We create table to store the uploaded files



CREATE TABLE "uploads" (
 "id" int DEFAULT 0 NOT NULL,
 "mimetype" Varchar NOT NULL,
 "data" Bytea
);

ALTER TABLE "uploads" ADD CONSTRAINT "uploads_pk" PRIMARY KEY ("id");

CREATE SEQUENCE uploads_seq START 1;
ALTER TABLE uploads ALTER COLUMN id SET DEFAULT nextval('uploads_seq'::text);

Set up the application

At application start we will initialize Active Record. Open Global.asax.cs file and edit method Application_Start(). After RegisterRoutes we add the initialization piece of code:



protected void Application_Start()
{
  RegisterRoutes(RouteTable.Routes);

  // load configuration from Web.config
  Castle.ActiveRecord.Framework.IConfigurationSource source =
    System.Configuration.ConfigurationManager.GetSection("activerecord")
    as Castle.ActiveRecord.Framework.IConfigurationSource;

  // Initialize and mention which types define our model
  Castle.ActiveRecord.ActiveRecordStarter.Initialize(source,
    typeof(Models.Upload));
}

The UploadController class

Basically we’d need three different URLs: Add – to upload new file; Get- to get uploaded file and finally Index which gives us list of all uploads.

We’ll create UploadController class in Controllers directory. Then we implement the three methods.



using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Web.Mvc.Ajax;

namespace UploadToDb.Controllers
{
    public class UploadController : Controller
    {
        [AcceptVerbs(HttpVerbs.Post)]
        public ActionResult Add(HttpPostedFileBase file)
        {
            if (file != null)
            {
                Models.Upload upload = new UploadToDb.Models.Upload();
                upload.Mimetype = file.ContentType;
                upload.Data = new byte[file.ContentLength];
                file.InputStream.Read(upload.Data, 0, file.ContentLength);
                upload.Save();
            }
            return Index();
        }

        public FileContentResult Get(int id)
        {
            Models.Upload upload = Models.Upload.FindById(id);
            return File(upload.Data, upload.Mimetype);
        }

        public ActionResult Index()
        {
            this.ViewData["uploads"] = Models.Upload.FindAll();
            return this.View("Index");
        }

    }
}

Method Add() calls Index() after the file upload finished, those way we get the list of the uploads after we upload new file.

The HTML view

Created directory Views\Upload and add there view Index. I won’t select a master page for the purpose of the presentation. I also won’t use strongly-typed view, but just will thread the ViewData as a dictionary.



<%@ Page Language="C#" Inherits="System.Web.Mvc.ViewPage" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>File uploads</title>
</head>
<body>

    <h3>1.List of uploads</h3>
    <%
        UploadToDb.Models.Upload[] uploads = (UploadToDb.Models.Upload[])this.ViewData["uploads"];
        foreach (UploadToDb.Models.Upload upload in uploads.OrderBy(x=> x.Id))
        {
    %>
            <div><%= Html.ActionLink(upload.Id.ToString(), "Get", new { upload.Id })%></div>
    <%
        }
    %>
    
    
    <h3>2.Upload new file</h3>
    <% using (Html.BeginForm("Add", "Upload", FormMethod.Post, new { enctype = "multipart/form-data" })) 
       { %>
        Choose file: <input type="file" name="file" />
        <input type="submit" />       
    <% } %>
    
    
</body>
</html>

Basically we have two parts here.

Part one is a list of all the uploaded files. It creates list of links to open the uploaded files via the "Get" method.

Part two is an html multipart form used to upload new file. After the file upload finished, we invoke again the Index controller method to list all the files uploaded to the database.

To upload file to database run the application and navigate the browser to ~/Upload/ directory.

I've got that screen after two files uploaded:

Enjoy!

Atanas Hristov

Logging with log4net

2009-09-04T09:21:00.001-07:00

Log4net is a very powerful tool to get information from running application. After deployment your code has to deal with environment that is more or less different than on your development machine. Log4net not only provides your application with powerful logging where you can specify a lot of options and levels, but you can even dynamically turn on and off logging for different classes while the application is running at the same time.

The homepage of the project is:
http://logging.apache.org/log4net/index.html

I’m about to show you the way I’m usually using log4net in my projects.

Step one

The very first step is to add reference to log4net.dll to the project.

Initialization of log4net

It has to be done once in your application. You can prepare and run static initializer in the manner of:

 
public class Initializer
{
    private static object _locked = new object();
    protected static bool initialized = false;

    public static Initializer() { Init(); }
    
    public static void Init()
    {
        lock (_locked)
        {
            if (initialized)
                return;

            log4net.Config.XmlConfigurator.Configure(); // run once at app startup
    ...
        }
    }
}

Then call Initializer.Init() at application start-up from your Global.aspx or Main() for example.

Add logger for one class

One possibility to use log4net is to create separate logger for one class only. Thereof you can:

a/ write to separate and dedicated for that class only log file,
b/ or you can have different formating for logging messages from that class,
c/ or you can set different log level for the log messages from that class,
d/ or just because the class name could be written along with the logging messages so it will be easy to localize the part of the code from where the message comes.

Here is part of declaration of class named "McChannel" for which class we will define class logger.

 

// (1) add using directives:
...
using log4net;
using log4net.Config;

[ActiveRecord("mc_channels")]
public class McChannel : ActiveRecordBase
{
    // (2) declare and initialize static per class logger
    private static readonly ILog log = LogManager.GetLogger(typeof(McChannel));
...
}

From inside the body of that class you can use the logger "log" like:

 

  log.Debug("Selecting channel names at.");
  log.DebugFormat("Addiding channel {0}", one.Channel_name_official);

You have log.Debug(), log.Info(), log.Warn(), log.Error(), log.Fatal() methods you use for logging and they all have the corresponding extended with string formatting methods: log.DebugFormat(), log.InfoFormat(), log.WarnFormat(), log.ErrorFormat(), log.FatalFormat(). In the exact priority order as listed here the Debug() has the lowermost priority.

In your configuration (see below) you have to set which level of logging you want to log. The logging levels as they are defined in order of decreasing priority are:

OFF: no logging at all.
FATAL: only log.Fatal() messages will be logged
ERROR: log.Error()and higher will be logged
WARN: log.Warn() and higher will be logged
INFO: log.Info()and higher will be logged
DEBUG: log.Fatal()and higher will be logged
ALL: all logging methods will be logged.

Configuration of log4net in App.config or Web.config

Let's prepare simple configuration for log4net.

First in configSections we add element section with attribute name="log4net".
Then we add sub element "log4net" to element "configuration".

We create appender "RollingFileAppender" which defines where we write logging messages and what the pattern for formatting the log messages is. Furthermore the files will be rotated.

We can have more than one appender in your configuration.

Then we default set priority levels for the whole application to "ERROR" - see element "root" - but we define for class "McChannel" priority level of "DEBUG".

Here is the complete example:

 

<?xml version="1.0"?>
<configuration>
  <configSections>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net" />
  </configSections>
  <log4net>
    <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
      <file value="D:\Logfile.txt" />
      <appendToFile value="true" />
      <rollingStyle value="Size" />
      <maxSizeRollBackups value="100" />
      <maximumFileSize value="1024KB" />
      <staticLogFileName value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date %-5level %logger - %message%newline" />
      </layout>
    </appender>
    <root>
      <!-- ALL DEBUG INFO WARN ERROR FATAL OFF -->
      <!-- Setup the root category, add the appenders and set the default level to ERROR -->
      <priority value="ERROR" />
      <!-- Set the default logger  -->
      <appender-ref ref="RollingFileAppender" />
    </root>
    <logger name="McChannel">
      <!-- Only for the logger for class McChannel we set level to DEBUG -->
      <level value="DEBUG" />
    </logger>
  </log4net>
</configuration>

The output of logging messages from class McChannel goes to D:\Logfile.txt after we run the application.

this.Dispose()

Log4net is very flexible. You can add the logging messages into a database table, you can use the TraceContext of ASP.NET, the console appender can produce colorized output, you can append to the Application event log in Windows, address Windows Messenger Service, send emails with logging messages and many more.

Have a nice weekend!

Atanas Hristov

ASP.NET Error Logging with ELMAH

2009-08-07T07:06:00.000-07:00

Debugging production code is always a challenge. From my experience I have used the Windows event logs and the Apache log4net so far.

Most of the time log4net is the solution for all my needs and I like how flexible it is. But they were situations where the logging solution was not enough. The real problem occurs if in your application you get unhandled exceptions. You know - database connection broken, network downtime, system software updates - it's in many ways possible to throw the application into confusion without having even the near idea where to look for. And this is where ELMAH comes to the rescue.

You can include ELMAH in your projects with a little effort and even with the default configuration you take benefits. ELMAH can log errors for you to different places - from xml files to database servers but the easiest way is to just store error messages into memory. ELMAH will give you a way to check for unhandled exceptions from special URL on your ASP.NET site.

Addiding ELMAH to a project

Having heard for ELMAH from Hanselminutes I decided to give a try.
There was a project under active development where new versions uploaded on the staging server very frequently, even many times a day.

After the download of the binaries I just added a reference to Elmah.dll into the project. Then following the instructions on the ELMAH documentation I made few additions to the Web.config file.

a/ I added to "configSections":


    <sectionGroup name="elmah">
      <section name="security" requirePermission="false" type="Elmah.SecuritySectionHandler, Elmah" />
      <section name="errorLog" requirePermission="false" type="Elmah.ErrorLogSectionHandler, Elmah" />
      <section name="errorMail" requirePermission="false" type="Elmah.ErrorMailSectionHandler, Elmah" />
      <section name="errorFilter" requirePermission="false" type="Elmah.ErrorFilterSectionHandler, Elmah" />
    </sectionGroup>

b/ Then added into "httpHandlers":


  <add verb="POST,GET,HEAD" path="elmah.axd" type="Elmah.ErrorLogPageFactory, Elmah" />

c/ and at the end into "httpModules":


  <add name="ErrorLog" type="Elmah.ErrorLogModule, Elmah"/>

I also added another configuration option to enable opening the ELMAH views from remote connection, not only on the server, into section "configuration" I added:


  <elmah>
    <security allowRemoteAccess="yes" />
  </elmah>

That was everything necessary to include ELMAH to the project.

Did I say - ELMAH is wonderful!

Having ELMAH included to the web application with this configuration, we have got the error logging information accessible at http://APPHOME/elmah.axd.

We put into the staging server only well unit-tested code. Once as we did changes on the database schema we have forgotten to patch the database where the staging server connects.

During the integration tests the application raised an exception. On the browser the exception information was not very helpful (see: yellow screen of dead). Into the log files generated by log4net there was nothing mentioned. Then we opened the ELMAH page and we saw the reason for the exception:

ELMAH is a tool to help you with any ASP.NET project. Use it right now.

ASP.NET Globalization

2009-08-03T03:58:00.000-07:00

I just finished a project where one of the requirements was to localize completely the input the user gave and the output of values (numbers, date) sent back to the user.

There is a nice way in dot.NET to set current culture information on a thread. You can for example examine the Request.UserLanguages - which is an array of strings and shows you which locales and languages the browser accepted - and then prepare CultureInfo object and assign that object to CurrentThread.

That way you set culture info for every request on the webserver. You use later the culture info information from CurrentThread to parse the user input and to write back localized values to the user.

Set CultureInfo for CurrentThread

The very first step is to set the culture information on CurrentThread on per page request basis. To do so edit function Application_BeginRequest from file Global.aspx.cs.


      protected void Application_BeginRequest(object sender, EventArgs e)
      {
          // you could use Request.UserLanguages
          // to set appropriate culture information
          System.Globalization.CultureInfo ci = …;          
          System.Threading.Thread.CurrentThread.CurrentCulture = ci;
      }

Set ASP.NET AJAX in your Master Page or View Page

Edit file Site.Master (or the MasterPage or ViewPage where the ScriptManager is.
Set EnableScriptGlobalization attribute to "true". Insert bug-fix for Number.parseLocal


<form id="frm" runat="server">
    <asp:ScriptManager
ID="ScriptManager1"
runat="server"
EnableScriptGlobalization="true">
        <Services>
            <asp:ServiceReference Path="~/WebServices/Service.asmx" />
            ...
        </Services>
    </asp:ScriptManager>

<script type="text/javascript">
    Number.parseLocaleFixed = function(value) {
        return Number.parseLocale(value.replace(' ', ' '));
    }
</script>

Parse User Input in ASP.NET Ajax

To parse user input of numbers use Number.parseLocaleFixed() javascript function. To parse user input of date use Date.parseLocale() javascript function.
Example:


 Var numb = Number.parseLocaleFixed(
     document.getELementById(‘txtNumb’).value);

Parse user input in ASPX page

Use the Parse() functions of the expected type. Specify the culture info in Parse(). Take the culture info from CurrentThread.


 DateTime dt = DateTime.Parse(s,
         System.Threading.Thread
            .CurrentThread.CurrentCulture);

Write localized Information to the page

To write localized values to the page use the culture information from CurrentThread:


 <%= dt.ToString(“d”, System.Threading.Thread
           .CurrentThread.CurrentCulture) %>

To write localized pattern for validation of date input field you can use something like:



   CultureInfo ci = System.Threading.Thread
            .CurrentThread.CurrentCulture;

   // validation of date input
 string dSeparator = ci.DateTimeFormat.DateSeparator;
 if (dSeparator == ".") dSeparator = @"\.";
 string dPatternExpr = String.Format(@"^(|[0-9]{{1,4}}{0}[0-9]{{1,4}}{0}[0-9]{{1,4}})$",
     dSeparator);

 valSigningDate.ValidationExpression = dPatternExpr;

 // validation of number input
 string nDecimalSeparator = ci.NumberFormat.CurrencyDecimalSeparator;
 if (nDecimalSeparator == ".") nDecimalSeparator = @"\.";
 string nPatternExpr = String.Format(@"^[-+]?[0-9]*{0}?[0-9]*$",
     nDecimalSeparator);

 valSinglePayment.ValidationExpression = nPatternExpr;

Atanas Hristov

Using Entity Framework with SQLite - Installation

2009-08-01T07:56:00.000-07:00

SQLite is a simple but powerful open source database engine which you can use among everything else at development time and later connect your application to database server at run time.

Tools I have found to be pretty helpful to administer SQLite databases are: SQLite Expert Personal and sqliteadmin.

To use SQLite with the Entity Framework you need ADO.NET Provider. A complete provider is System.Data.SQLite.

Download file SQLite-1.0.65.0-setup.exe and install to appropriate location. I used directory C:\Programme\SQLite.NET as installation directory. In subdirectory bin into the installation directory you'll find two libraries - "System.Data.SQLite.Linq.dll", "System.Data.SQLite.dll" - which you optionally can register into the global assembly cache (gacutil -I ). To connect the Entity Framework to SQLite database you'll need to add references to these two assemblies.

Now, there is a nice dot.NET project on MSDN - EFQuerySamples - which demonstrates the Entity Framework with the well known Northwind database. You can use that application to learn the syntax of the Entity Framework queries and even to see the generated SQL. Download the project and unzip the file.

To get the EFQuerySamples running against SQLite database, there is a supplement to the MSDN project - EFQuerySamples_SQLite. You need to copy from this over the original project the following files.

Having the two projects unzipped next to each other copy:


file EFQuerySamples_SQLite\App.config to EFQuerySamples\App.config
file EFQuerySamples_SQLite\Entity Framework Query Samples.csproj to EFQuerySamples\Entity Framework Query Samples.csproj
file EFQuerySamples_SQLite\DB\northwindEF.db to EFQuerySamples\DB\northwindEF.db
file EFQuerySamples_SQLite\Schemas\NorthwindEFModel.SQLite.ssdl to EFQuerySamples\Schemas\NorthwindEFModel.SQLite.ssdl

Open the Visual Studio solution from EFQuerySamples.

Add references to the assemblies System.Data.SQLite and System.Data.SQLite.Linq.

Open file App.config and add new DbProviderFactory:


  
  <system.data>
    <DbProviderFactories>
      <remove invariant="System.Data.SQLite"/>
      <add name="SQLite Data Provider" invariant="System.Data.SQLite" 
           description=".Net Framework Data Provider for SQLite" 
           type="System.Data.SQLite.SQLiteFactory, System.Data.SQLite, Version=1.0.65.0, Culture=neutral, PublicKeyToken=db937bc2d44ff139"/>
   </DbProviderFactories>
    </system.data>

Take care of the Version in attribute type, make sure equals the version of the System.Data.SQLite.dll you downloaded.

Also in App.config there should be addition to section connectionStrings coming with the supplement project:


  
  <connectionStrings>
    <add name="NorthwindEF (SQLite)" connectionString="provider=System.Data.SQLite;metadata=Schemas\NorthwindEFModel.csdl|Schemas\NorthwindEFModel.msl|Schemas\NorthwindEFModel.SQLite.ssdl;Provider Connection String='Data Source=DB\northwindEF.db'"
      providerName="System.Data.EntityClient" />


    ...

Now you can run the EFQuerySamples application, choose the SQLite connection and run the various examples.

Enjoy!

Atanas Hristov