Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
hibernate-orm/documentation/status.md

3.0 KiB
Raw Blame History

Status of the documentation overhaul (5.0 version)

Overall the plan is to define 3 DocBook-based guides. The intention is for this document to serve as an outline of the work and a status of what still needs done.

NOTE : entries marked with strike-through indicate that the content is believed to be done; review would still be appreciated.

User Guide

Covers reference topics targeting users.

  • Prefix
  • Architecture
  • DomainModel
  • Bootstrap
  • PersistenceContext
  • Database_Access
  • Transactions
  • JNDI
  • Fetching - still need to document batch fetching, subselect fetching, extra laziness and EntityGraphs
  • Flushing (to be written)
  • Cascading (needs lots of work)
  • Locking (needs some work)
  • Batching (needs lot of work - not started - open questions)
  • Caching (needs some work)
  • Events (need some work)
  • Query - HQL/JPQL
  • Query - Criteria
  • Query - Native (copy from old)
  • Multi_Tenancy (needs some work)
  • OSGi (right place for this?)
  • Envers (right place for this?)
  • Portability (needs some work)

Domain Model Mapping Guide

Covers mapping domain model to database. Note that a lot of the "not started" content exists elsewhere; its merely a matter of pulling that content in and better organizing it.

  • Prefix
  • Data_Categorizations
  • Entity (needs some work)
  • Basic_Types
  • Composition
  • Collection (needs some work)
  • Identifiers (mostly done - needs "derived id" stuff documented)
  • Natural_Id
  • Secondary_Tables (not started) - logically a joined in-line view
  • Associations (not started)
  • Attribute_Access (not started)
  • Mapping_Overrides - AttributeOverrides/AssociationOverrides (not started)
  • Generated_attributes (not started)
  • "columns, formulas, read/write-fragments" (not started)
  • Naming_Strategies - implicit, physical, quoting (not started)
  • Database_Constraints - pk, fk, uk, check, etc (not started)
  • Auxiliary_DB_Objects - does this belong here? or somewhere else (integrations guide) discussing schema tooling?

Integrations Guide

  • Services&Registries (pretty much done)
  • IdGeneratorStrategyInterpreter (not started)
  • custom Session/SessionFactory implementors (not started)
  • ???

Overall

  • I really like the idea of each chapter having a title+abstract. See userGuide/chapters/HQL.xml for an example.
  • I really like the idea of each chapter having a "Related Topics" (?)sidebar(?). See userGuide/chapters/HQL.xml for an example. I am not sure <sidebar/> is the best element for this concept, but I could not find a better one on cursory glance. I noticed literallayout used in a few DocBook examples for something similar.