Documentation proposal

Overall I propose we have the following documents:

• Hibernate Manual - The main reference manual. The intention is to overhaul the reference manual and re-integrate the pertinent information from the dev-guide. We’d need to determine whether a separate dev-guide still makes sense. The intention for the dev-guide was always to describe SPI/integration concerns. However some "user information" definitely made its way in there.

• Hibernate Domain Model Mapping - Discussion of annotations and hbm.xml mapping of the domain model. This is such a massive topic that it is already split into multiple chapters in the existing manual.

• Dev Guide - if we decide we wish to keep that doc separate. The name should be more like "Hibernate Integrations Guide".

Proposed topics - Hibernate Manual

Order is still tbd

Preface

See the updated preface from manual.

Architecture

Describe Hibernate at a high-level. See the updated page from manual.

Domain Model

Mainly the same topic as content/persistent_classes.xml from the manual, but augmented with information from other sources such as Anthony’s discussion of equals() and hashCode() (https://developer.jboss.org/wiki/EqualsandHashCode), etc

The intent here is to discuss the purely Java aspects of defining a domain model. As mentioned above, the plan is a separate doc for decribing how to map a domain model.

Persistence Context

Discuss Session/EntityManager as a persistence context in regards to state (managed, transient, detached) transitions. chapters/pc/Persistence_Context.xml in the dev-guide is a great start. The information from the content/readonly.xml manual chapter should also be folded into this discussion imo.

Database Access

Discuss access to the database. Database_Access.xml from the dev-guide and parts of the updated content/bootstrap.xml chapter from the manual combined make a great start.

Transactions and Locking

Discuss transaction, concurrency and optimistic/pessimistic locking. Great start in a combination of

• updated content/bootstrap.xml chapter from the manual

• chapters/transactions/Transactions.xml in the dev-guide

• Locking.xml in the dev-guide

Fetching

I really like the discussion I started in the dev-guide chapter chapters/fetching/Fetching.xml

Batching

First we need to decide what all to discuss here as that phrase has so many connotations. Do we cover

• JDBC batch updates?

• StatelessSession?

• Session w/ incremental flushing?

• Java EE batching?

Any/all of the above? Others?

The updated content/bootstrap.xml chapter from the manual has a good grouping of the settings that effect JDBC batch updates.

Second-level Caching

Again the updated content/bootstrap.xml chapter from the manual has a good grouping of the settings that control caching. Caching.xml from the dev-guide is a good structure I think.

Events

Discuss Hibernate event listeners as well as JPA callbacks.

HQL/JPQL

Discuss HQL/JPQL

Criteria queries

Discuss JPA Criteria queries. Still have appendix for legacy criteria api

Native queries

Discuss native (SQL) queries

Multi-tenancy

Discuss multi-tenancy

OSGi

Discuss OSGi

Envers

Discuss Envers

Spatial

Discuss hibernate-spatial

Performance Monitoring

Discuss Statistics and SessionEventListener. See the updated content/bootstrap.xml chapter from the manual, as well as the content/performance.xml chapter from the manual

Best practices

See content/best_practices.xml from the manual

Portability

Discuss database portability, environment portability and even JPA provider portability.

Services and Registries

Or should this remain solely a "dev guide" discussion?

Additional modules(?)

Essentially, is content/additionalmodules.xml from the manual of any value?

Proposed topics - Hibernate Domain Model Mapping

The discussion in src/main/docbook/devguide/en-US/Data_Categorizations.xml is a great start to this document I think.

In addition to the various chapters on mapping in the manual, there are lots of great external sources of information we could pull from for this document.

Basic types

Discuss the basic types

Entities

Discuss entities

Associations

Discuss various association types