This is a proposal for a new structure of the NHibernate reference documentation. The goal is to discuss it and get some feedback from the community.

Goals

The goals of the restructuring of the documentation are:

• move from "feature oriented" to "solution oriented". For instance, instead of having a chapter about the "version" xml element, there is a chapter about "concurrency". So the reader has a problem to solve, and he finds a chapter that explains, how NH solves it. The reader can't know that he needs a version element. Such a chapter should cover all elements of a certain problem, in the given example this are the version xml-element, the optimistic-lock xml-attribute of classes and properties, explicit version increment, locking and so on.
• Additionally, there shall be a complete reference of the mappings, configurations and others in an appendix that links to the chapters.
• More diagrams for mapping strategies
• More best practices and patterns
• Fill gaps where the documentation is not complete (enough), for instance special HQL features, user types, interceptors and events, connection factories and other extensions, (new) proxy factories etc.

Structure

Part 1: First Steps

In this part: a high-level overview of the whole picture.

Quick start

• simple program that runs "out of the box"
• not too much code, not too much explanation (but links to chapters)
• includes inheritance, reference, list
• includes schema generation
• includes some simple hql
• includes configuration for sqlserver, oracle, mysql

Architecture and basic concepts

•  Architecture (diagrams)
•  "Factory-Chain" Configuration => SessionFactory => Session => Transaction / Query
•  Instance States
•  Session Cache (see also "Working with persistent objects")
•  Application Architectures (referenced assemblies from application layers)

Setting Up

• Three ways: nhibernate.cfg.xml, app.config, programmatic
• Dialects and Drivers (See also Appendix "full list of Drivers / Dialects")
• ProxyFactory configuration (see "lazy loading")
• SessionProvider, contextual sessions
• Getting a connection (connection provider, user provided, connection release mode)
• How to set up a Project, minimal program
  • configuration file
  • mapping files (see "OR Mapping Basics")

Part 2: Writing and Mapping Classes

In this part: Static view, classes, mappings, db schema

Persistent classes

• Example poco, basic rules
• Object Identity
  • id generators
  • best practices
  • composite keys (see also "Working with legacy databases")
  • component keys (see also "Working with legacy databases")
• Overriding Equals and GetHashCode
• Optional: Version (see optimistic locking)
• lifecycle callbacks
• validation
• see also: lazy loading (because of virtual)

OR Mapping Basics

• Manage mapping files
  • as xml files
  • as embedded resources
  • modular mapping files
  • alternatives (attributes, FNH)
• Using quoted identifiers
  • NH Types (see also: "Extend NH behaviour - user types", Appendix "Full List of Types")
• Naming conventions
• Property / field (access strategy)

Mapping primitive values and single ended references

• properties
• references many-to-one
• references one-to-one
• map several classes to one table: components
• dynamic components
• map a class to several tables: join
• any types

Mapping Collections

• persistent collections
• set, list, map, bag, array, primitive-array
• one-to-many relations
• many-to-many relations
• composite-elemements
• collection performance
• Sorted collections

Mapping Inheritance

• Table per Hierarchy
• Table per Concrete Class
• Table per Class
• Mixing strategies

Mapping to legacy databases

• composite keys
• component keys
• property-ref

Generating The Database

• The schema export tool
• not null
• foreign keys
• indexes
• unique keys
• Auxiliary Database Objects

mapping file generation from entity

Part 3: Working with Persistent Objects

In this part: Dynamic view, sessions, queries, modifications, transactions etc.

Working with sessions

• sessions, session cache, flushing
• cascading
• detached objects, reattaching

Querying

• Introduction, when to use which kind of query

HQL Queries

• Syntax
• Multi Query

Criteria Queries

• API
• Multi Criteria

Using NH filters

Lazy loading and fetching strategies

• fetching strategies
• collections
• references (proxies)
• load
• Utility.Initialize
• batch fetching

Updating and deleting

• updating, batch-updates, HQL updates
• deleting, one-shot-delete, HQL delete

Transactions And Concurrency

• Transaction factory (see also: setting up)
• Concurrency
  • Optimistic Locking
    • Version columns
    • Property level
    • Force version increment
    • application version check
  • Pessimistic Locking

Part 4: Enhanced Features

In this part: Features that are not used by everyone. They are not important to understand to work with NH.

Using Native SQL

• Sql queries
• custom SQL for query/update/insert/delete
• precompiled queries
• Using SP's, db functions and triggers
  • property update/insert
  • property generated
  • property formula
  • see also: "Generating The Database - Auxiliary Database Objects"
• Using Database Views

Caches

• second level cache
• query cache

Meta API

Extend NH behaviour

• user types
• Interceptors
• events
• connection provider
• transaction factory
• session provider

Part 5: Examples

In this part: examples

Appendix

In this part: lists and references. The references (eg. mapping xml elements, dialects etc are important to find the documentation. So there are basically only links to chapters)

Trouble shooting

Configuration Reference

• Getting a connection (connection provider, user provided) (setting up)
• proxy generator (lazy loading)
• cache configuration (optimizing)
• Transaction factory (setting up)
• Dialects (setting up)
• Outer join fetching (lazy loading?)
• logging (trouble shooting)
• naming strategy (mapping)

Full List of Dialiects

Full List of Drivers

XML-Mapping full reference

Full List of Type