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
Criteria Queries
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
On the other hand if you intend to produce a large amount of Screen Printing Machine items, you will have to invest in the industry.