Mar 31 2008

NHibernate 2.0 Alpha

Tag: NHibernateSymon Rottem @ 10:41 pm

For those of you who aren’t already in the know, the new version of NHibernate has entered it’s alpha release stage. This brings the codebase almost into line with the current Java Hibernate release (3.2) with a couple of exceptions so this is definitely something to write home about.

A few of the key things that I’ve been waiting for in this release are:

  • Inspection/traversal, modification and cloning of ICriteria
  • Table per subclass mapping with a discriminator
  • MultiCriteria
  • Mapping of one class to several tables using the <join> mapping.
  • Events and listeners

The changelog goes some of the way to explain the new changes in more detail than I have, but there’s a more comprehensive rundown on Ayende’s blog if you want a little more meat to chew on. In addition, Fabio Maulo (one of the NHibernate developers) noted that there are a couple of additional features that are notably missing from the changelog; namely the Merge and Persist methods on ISession and extended cascade mappings, unionsubclass and on-delete on the mapping side.

In reality you do need to take some care before upgrading since this is an alpha, but you can rest assured that the code is not brand spanking new, untested and unused. As Ayende mentions in his blog post…

We call this alpha, but many of us are using this in production, so we are really certain in its stability.

Anway, the call is out to start playing with the new version so the developers can get some real-world feedback on how it’s working in your environment and a chance to fix any issues before they give it their blessing for use in more critical and widespread environments. The Castle trunk has been updated to use this new release, so it can’t be too bad now, can it?

If you do decide to upgrade there are some breaking changes to be aware of, but most of them shouldn’t cause you major problems unless you’ve decided to bend and twist NHibernate more that the average user.

Also worthy of note is that there don’t appear to be updated docs available yet, but since most of the features of the new version match those of the production Java version their docs should help you get a good idea of where you are going.

You can keep up with what’s going on with others who are using the new version, get help and can provide feedback on the new NHibernate mailing list as well as the forums. At the moment the mailing list is very active so it’s a great alternative to the forums if you don’t get any response there.

I’ll be taking the new NHibernate for a whirl myself very shortly and will post on my experiences as they happen.

Mar 26 2008

Where does all the time go?

Tag: UncategorizedSymon Rottem @ 11:44 pm

Wow.  Time passes – fast.

I’ve been working hard on taming the docs for Castle as many of you already know and although I’m making progress it sometimes feels very slow.  This is especially true when I find myself with too many other things on my hands – business travel to Italy, refactoring code,  mentoring colleagues and trying to grok legacy software from the bowels of a system at work to name but a few.  The last is especially fun when the developers who wrote the code have not been with the company for years now…

So, the reward for all this hard work?  More hard work?  No – sod it – I’m taking few days off to drive around the south of France.

Regardless, in an effort to maintain forward motion on the MonoRail docs, for those of you who’ve offered to contribute, now’s the time to step up to the plate (or crease if you’re from this side of the pond and prefer the cricket analogy).  The source is all in the contrib source repository and I’m happy for people to put their hand up for a section or subsection (hell, even a paragraph!) that is inadequately documented, needs reworking, proof reading – anything.

If you’ve ever wanted to get involved in Open Source this is going to be an easy entry point – and you get to learn even more which can help you get closer to the code!  Before I began the restructuring I had a reasonable idea of what I was doing with MonoRail, but now I feel like I know soooo much more…any hey – now I know how to work with DocBook too.

Anyhoo – I’ll be back in a couple of days.  If you want to help out drop me a line.  Until then…à bientôt.

Mar 22 2008

NHibernate Proxy Generator

Tag: NHibernate,Open SourceSymon Rottem @ 4:11 pm

I just stumbled over an interesting post on William C. Pierce‘s blog explaining how to set up NHibernate to run in a a medium trust environment and still get the benefits of lazy loading.

I’ve seen a few queries about how to do use lazy loading under medium trust in the past but have never really investigated it myself having assumed it was just one of those things you couldn’t do since proxies are generated through reflection and reflection permissions are not granted in medium trust environments.

Well it turns out that isn’t the case if you get a little creative.

What William has done is to create his own proxy factory that NHibernate can be configured to use so it will provide proxies that were generated at compile time where you have full trust rather than generating proxies at runtime where the reflection permissions are restricted.
He’s also provided a tool to generate those compile time proxies and released his hours of hard work as the NHibernate Proxy Generator (or NPG) so you don’t have to invest time of your own.  The project is still in it’s infancy but it’s released under the Apache License 2.0 so you can download the source and contribute should you so desire.

William has provided more information on how NHibernate can be configured to run in medium trust and use NPG generated proxies in his blog post so head on over there if you’re stuck with medium trust and still need lazy loading.

Mar 19 2008

DocBook MonoRail Docs in Contrib

Tag: Castle,Open SourceSymon Rottem @ 12:19 am

For those who don’t lurk on the Castle Development mailing list, the new DocBook version of the MonoRail documentation I’ve been working on has now been submitted to the Castle Contrib repository. If you want to download a copy of the source to build and play with you can find it here:

This initial checkin contains only the MonoRail DocBook source files in their initial, unedited state, NAnt build scripts to generate the output and the toolchain required to do the build.

At this stage output generated includes single page HTML, multi-page HTML (one page per chapter) and a CHM file. I anticipate the addition of PDF and VS 2005 add in documentation formats in the near future. The following links provide a sample of the current generated output:

To build the documentation you will need to have a Java runtime installed, however you can easily use IKVM.NET as an alternative as long as you don’t mind making some minor changes in the build files. Each book can be built by executing NAnt against its build file ( for MonoRail, for example) or the whole tree can be built by using the file. Keep in mind that right now there are only MonoRail docs, so either way it’s essentially the same thing.

Right now the content is only basically styled and only some code blocks have been set up for syntax highlighting. There are also likely to have been a couple of errors in transferring the data and several internal and external links are still broken. Since I have now got an initial buildable version in place I should be able to return my focus to fixing these and other content issues as well as continue work on migrating other frameworks in the Castle stack to the DocBook format.

Any feedback is welcome.

Mar 18 2008

DocBook in NAnt

Tag: UncategorizedSymon Rottem @ 10:10 am

Over the weekend I changed the way I’ve been building the new DocBook based documentation for Castle so that it’s more in line with normal automated build processes.

The process is somewhat new to me – I’ve never written an NAnt script in my life, so there’s been a bit of a learning curve involved…especially when trying to get do DocBook XSL transformations with syntax highlighting!

For example, take the following:

<exec program="xsltproc">
	<arg value="--output" />
	<arg file="${build.single.dir}/index.html" /><!-- file to output transform results to -->
	<arg file="customizations/html_chunked.xsl" /><!-- xsl to do the transforming -->
	<arg file="${source.dir}/book.xml" /><!-- xml file to transform -->

This is a pretty straight forward NAnt exec task that’s running xsltproc.exe from the Win32 build of libxslt – an XSL transformation engine. Seems easy enough, right?

Ok, I chose this particular engine because I’ve chosen to make my DocBook files modular so I don’t have one giant XML file containing all the content. To do that I’ve used XIncludes and to make the engine support them all I need to do is add one argument:

<exec program="xsltproc">
	<arg value="--xinclude" />
	<arg value="--output" />
	<arg file="${build.single.dir}/index.html" /><!-- file to output transform results to -->
	<arg file="customizations/html_chunked.xsl" /><!-- xsl to do the transforming -->
	<arg file="${source.dir}/book.xml" /><!-- xml file to transform -->

So good so far.

Where I ran into trouble was that I want to use the syntax highlighting in DocBook XSL – now things turn ugly. I can’t use my nice simple transformation engine anymore because the xslthl syntax highlighting library used by DocBook XSL is in Java and that means I need to use a Java based XSL transformation engine – I’ve chosen Saxon…but Saxon doesn’t support XIncludes out of the box. Aargh! Ok, there’s a way out of this, right? You betcha. You need to hook in Xerces so Saxon can use it for resolving XIncludes.

So, in summary, if I use Saxon, hook in the xslhtl package for syntax highlighting, then Xerces for XInlcude pre-processing to do what is otherwise the same as the task above the resulting NAnt task looks like this:

<exec program="java" useruntimeengine="true">
	<arg value="-cp"/>
			<pathelement file="toolchain/saxon/saxon.jar"/>
			<pathelement file="toolchain/xslthl/xslthl.jar"></pathelement/>
			<pathelement file="toolchain/xerces-2_9_1/xercesImpl.jar"></pathelement/>
	<arg value="-Dxslthl.config=file:///${project::get-base-directory()}/customizations/highlighters/xslthl-config.xml"/>
	<arg value="-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
	<arg value="-Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
	<arg value="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration"/>
	<arg value="com.icl.saxon.StyleSheet"/>
	<arg value="-o"/>
	<arg value="${build.single.dir}/index.html"/>
	<arg value="${source.dir}/book.xml"/>
	<arg value="customizations/html_single.xsl"/>

Personally I think this is scary – there must be an easier way to do DocBook transformations that won’t cost you. Does anyone have any suggestions?

As a side note, if you want to do all of the above without installing Java the above task can be executed using IKVM.NET as described in my last post.

Mar 16 2008

IKVM.NET – Java without installing

Tag: UncategorizedSymon Rottem @ 7:57 pm

Working on the DocBook version of the Castle documentation this weekend I found that to be able to take advantage of the built in syntax highlighting features of the DocBook XSL package I need to use a Java plugin but the XSL processor I’ve been using doesn’t support the plugin. The solution, of course, is to move to a processor that’s Java based but that then means that the build server needs to have a Java runtime installed to execute…or so I thought.

It turns out that there’s this really cool project called IKVM.NET that provides a Java Virtual Machine in .NET that allows you to run Java applications in the .NET Runtime. After some reading and experimenting I managed to get it working, so now I can use that Java based processor without installing Java.

What’s more, this will help with another little problem I’ve been chewing over – the generation of PDFs using Apache FOP. Apache FOP appears to be the most mature Open Source FO processor out there and seems to be the recommended way of converting DocBook into PDF. The kink for me was – you guessed it – it’s another Java package.

Using IKVM can be as simple as executing ikvm.exe in place of Java on the command line. So instead of executing the following…

java -jar myapp.jar

…you can instead use…

ikvm -jar myapp.jar

IKVM also provides utilities for converting Java bytecode to .NET IL which allows you to generate a .DLL from a Java library that can be used directly in a .NET application. Very cool – I recommend having a look if there’s some fantastic Java library out there with no .NET equivalent.

To get all this all you need are a couple of DLLs and executables. Admittedly it’s a little heavy to deploy with your code at 26Mb but it’s nice to know it’s there as an option instead of being forced to install the “official” Java Runtime.

Mar 11 2008

Documenting Castle – Phase One Complete

Tag: UncategorizedSymon Rottem @ 12:58 am

After many hours slaving over the keyboard the existing MonoRail trunk documentation has been transferred to DocBook format! Wahoo! I think I’ve given myself a crick in the neck and a good dose of RSI but hell – it had to be done, right?

The newly proposed structure is in place (apologies for the deviations from my previous post) and the existing content has been copied across but it’s not finished yet – there’s still a whole slew of tasks to undertake:

  • The styles still need to be built to provide a nice look and feel.
  • The output needs to be customized for each of the formats (I’m planning on Single Page HTML, Chunked HTML, HTML Help, VS 2005 Documentation and PDF at this stage).
  • Link endpoints need to be fixed.
  • The generation process needs to be properly automated.
  • The content hasn’t been refactored yet…this comes last.

But progress is being made (and I have a day job too!) Fortunately, Nicolas Vitra – a colleague of mine – is helping out with the PDF generation and adding syntax highlighting to the code samples, so things should start moving faster.

If you want to see the current state of things there’s a version of the docs for review here. Note, however that this is not in any way considered to be release-worthy, it’s just a little sneak peek. The content will not be staying at that address and will be taken offline at some point in the not too distant future, although hopefully not before they go into production.

Please post comments related to the structure or any problems with the presentation. Just remember that the content has not yet been from what’s available on the Castle website so any comments on that score should wait until it’s available in source control so others can get involved in the editing process.

Anyway – enjoy.

Edit: The URL for the documentation has been updated to a new location temporarily. 

Mar 08 2008

Documenting Castle – Tool Friction

Tag: UncategorizedSymon Rottem @ 11:27 am

Working on the Castle documentation is bringing it’s own share of frustrations – scarily enough it’s not actually from wrangling the data but the tools I’m using to do the task. As Ayende is so often stating, friction is something that just shouldn’t be there.

I don’t mind coding XML by hand but I like to at least have an editor that will provide me with colorized markup and handle indenting for me and identify schema violations. Visual Studio 2005 – my development environment of choice – seemed like the right choice…except that the damned thing keeps borking on me with the following dialog when I try to paste data from some other file:

Visual Studio Borked

I have no idea what’s causing this and much googling hasn’t provided me with an answer.

Hmm. Next tool please…let’s try something completely different – XML Mind’s XXE Personal Edition. This isn’t a bad little tool in that is shows DocBook data rendered so that it’s somewhat visual allowing for a WYSIWIG editing. The problem for me is that you can’t get down to basic XML – they use a tree view of the nodes but it’s not straight XML – which screws up the copy paste approach I’m using to cobble together the existing content. Also, it’s a tad on the slow side. Grrr – more friction.

So, for the moment I’m using Eclipse to do my XML editing. Does anyone have any other suggestions on a validating XML editor that supports a multi document interface, auto indenting, tooltips and error highlighting based on the schema or DTD defined in the XML and that is, most important of all, free?

Alternately, tell me how I can get VS 2005 to work.

Drop me a line if you have any suggestions.

Mar 07 2008

Documenting Castle – Proposed Structure

Tag: Open SourceSymon Rottem @ 2:17 pm

This documenting thing is something of a challenge. I’ve been working industriously away on groking the DocBook schema a little better, figuring out the transformation tools and how to automate them while also trying to come up with a structure that makes sense for presenting the data that already exists.

To get myself off the ground I’ve elected to restructure the existing MonoRail 1.0 RC2 documentation first since there are so many people out there currently using it and it makes sense for my team. Certainly it makes sense to get the trunk code documented quickly too, but I know the RC2 stuff better at the moment, so that’s my starting point, like it or not.

Below is the chapter/section layout I’m proposing for MonoRail. This layout covers pretty much everything that’s in the existing user guide documentation and getting started guide. I think it exposes most of the concepts and addresses the concerns of those who are getting to know MonoRail in a top down fashion so the simple stuff is presented first and the concepts follow each other in a relatively intuitive fashion and it can be expanded on fairly easily. Of course, that’s just my take and you may not agree – feel free to provide constructive feedback and I’ll take it into consideration.

I’ll be posting more on the the process I’m going to use for generating the documentation shortly and should have a draft HTML version of the content based on the layout below using the existing content from the website in the next few days, so stay tuned!

1. Introduction
 1.1. Overview
 1.2. Background
  1.2.1. What is MVC
  1.2.2. Convention Over Configuration
 1.3. Why Use MonoRail
 1.4. How It Works
 1.5. Licence Information
 1.6. Support
2. Getting Started
 2.1. Requirements
 2.2. Creating the Project Skeleton
  2.2.1. Using the MonoRail Project Wizard
  2.2.2. Creating the Project Manually
 2.3. Controllers and Views
  2.3.1. Your First Controller and View
  2.3.2. Setting the Layout and Resuce
  2.3.3. Creating the Index View and Action
  2.3.4. Creating the Layout
  2.3.5. Seeing the Results
  2.3.6. Passing Values to the View
  2.3.7. Creating a Rescue
 2.4. Data Binding
  2.4.1. Simple Parameters
  2.4.2. Complex Objects
 2.5. Integrating with ActiveRecord
  2.5.1. Adding Assemblies
  2.5.2. Configuration
  2.5.3. Building the Model
  2.5.4. Initializing the Handler
  2.5.5. ActiveRecord Sacffolding
  2.5.6. Creating a CRUD Page Using DataBind
 2.6. Final Comments
3. Installation
 3.1. Running Under IIS
 3.2. Using Casini
 3.3. Mono with XSP
 3.4. Mono with Apache
  3.4.1. Configuration
  3.4.2. Apache Httpd2
  3.4.3. Application Deployment
 3.5. Deploying to a Shared Host
4. Configuration
 4.1. Formal Definition
5. Controllers
 5.1. Naming Convention
 5.2. Areas
 5.3. Actions
  5.3.1. Default Action
 5.4. Redirecting
 5.5. Data Binding
  5.5.1. The SmartDispatchController
  5.5.2. Other Useful Properties
  5.5.3. Simple Parameter Binding
  5.5.4. Custom Binding
 5.6. Wizards
  5.6.1. Wizard Controllers
  5.6.2. Wizard Action Provider
  5.6.3. Steps
  5.6.4. Nested Actions
  5.6.5. DoNavigate
  5.6.6. Conditional Steps
  5.6.7. The WizardHelper
  5.6.8. Windsor Integration
 6.1. Folder Structure Convention
 6.2. Selecting a View to Render
 6.3. Passing Values to a View
  6.3.1. The PropertyBag
  6.3.2. Flash
 6.4. Shared Views
 6.5. Cancelling a View
 6.6. Accessing Values Passed by the Controller
 6.7. View Engines
 6.8. Javascript and Ajax
7. View Components
 7.1. Creating a View Component
 7.2. Using View Components
 7.3. Passing Parameters
 7.4. Block and Nested Sections
 7.5. Built In View Components
  7.5.1. CaptureFor
  7.5.2. SecurityComponent
8. Filters
 8.1. Creating a Filter
 8.2. Ordering
 8.3. Skipping Filters
 8.4. Passing Parameters
 8.5. Block and Nested Sections
9. Layouts
10. Rescues
11. Authentication and Authorization
 11.1. Forms Authentication
 11.2. Filters
 11.3. Using PrincipalPermission
 11.4. The SecurityView Component
12. Helpers
 12.1. Built In Helpers
  12.1.1. AjaxHelper
  12.1.2. DateFormatHelper
  12.1.3. Effects2Helper
  12.1.4. FormHelper
  12.1.5. HtmlHelper
  12.1.6. PaginationHelper
  12.1.7. ValidationHelper
  12.1.8. WizardHelper
13. Resources and Localization
 13.1. Using Resources
 13.2. Setting Up the Current Culure
 13.3. Localization
14. Sending Email
15. Unit Testing
 15.1. The TestSupport Assembly
 15.2. Exposing the Website Application Directory
  15.2.1. Overriding GetPhysicalDir
  15.2.2. External Configuration
16. Integrations
 16.1. ActiveRecord
  16.1.1. Scaffolding
 16.2. Windsor Container
17. Advanced Topics
 17.1. Routing
  17.1.1. Routing
  17.1.2. Root Directory Mapping Workaround
 17.2. Dynamic Actions
  17.2.1. Dynamic Action Providers
 17.3. Scaffolding
 17.4. Extensions
  17.4.1. Custom Session Extension
  17.4.2. Exception Chaining Extension
  17.4.3. Creating Your Own Extensions
 17.5. Service Architecture
 17.6. Custom Bindable Parameters
 17.7. Using Resources to Store Views

Edit: After a comment on the mailing list from Erik Dahlstrand I noticed that somehow I’d forgotten to include the entire section on Helpers in the above structure so I’ve updated the list to include it.

Mar 02 2008

Documenting Castle – The Transformations Begin

Tag: UncategorizedSymon Rottem @ 11:24 pm

It has begun. The process of transforming the Castle user guide and getting started documentation to DocBook format is underway.

The process has so far involved writing a (truly and stupendously horrific) XSLT that transforms the selected parts of the original XML used to generate the Castle website into DocBook format, the creation of a simple batch file feeds all those XML files in each sub-folder to msxsl.exe with the XSLT sheeet to perform the transformation.

I say the XSLT is horrific mostly because my skills in the realm of XSLT authorship sucks like a vacuum cleaner and I’ve had to kludge something together without really knowing what I’m doing…

The really interesting part came from attempting to transform the HTML tables that were embedded in the original XML into the DocBook table format which doesn’t bear nearly enough resemblance to each other as I would have liked. After banging my head against the wall for a couple of hours the problem was solved using parts of someone else’s work who has much better XSLT skills than my own. See? I have no trouble resting on the shoulders of giants.

Regardless of the complete mess that does the processing, the damned thing works. It seems to have created documentation fragments that can be validated against the DocBook schema with only a couple of small exceptions. Yay!

Next step is to start reorganizing the information into logical groupings to present as chapters and subsections.

Wish me luck.

Next Page »