The purpose of this document is to capture design goals we want to incorporate into redesigning how mapping metadata is processed and how it is modelled.  Currently these roles are fulfilled by the classes in the org.hibernate.mapping package (model) and by the HBMBinder and AnnotationBinder classes (processing).  A major factor to keep in mind is that the org.hibernate.mapping package is used external consumers (users as well as by many other projects); they really need to have a voice here too.

Current prototypes kept @ https://svn.jboss.org/repos/hibernate/sandbox/trunk/new-metadata/

The basic idea is to split the model into 3 distinct parts:

1. logical model - describes the entity model in general terms without reference to specific database concepts.  Ideally we should avoid reference to specific "entity modes" here as well to facilitate a single model to describe the model regardless of the org.hibernate.EntityMode(s) used.  The implication is to avoid reference to java.lang.Class here.  See the entity mode discussion below.
2. physical model - describes the physical database schema
3. mapping - describes the mapping between (1) and (2).

See http://en.wikipedia.org/wiki/Data_model for a good general discussion of these topics.

Today the role of both (1) and (3) is fulfilled by o.g.mapping.PersistentClass and friends; (2) by o.h.mapping.Table et al.

Ideally (1) and (2) hav no reference to (3); (3) would define the "bindings".

Specific things to keep in mind:

• centralize validation if possible.  currently each binder is forced to perform validation.
• jpa defines most of (1), though in a very java class specific manner.
• all settings should be known prior to starting metadata processing; specifically dialect and connection provider.  This would allow us much better handling of keywords as quoted identifiers as we could get the list from dialect and the jdbc driver.  Currently we require users to explicitly quote all such identifiers.

Entity Modes

We need to account for entity modes in this model as well.  At the least, the current 3 entity modes though perhaps allowing extension here if feasible.  The question is how to best model this logical model / entity mode relationship.  This part I do not yet have clear in my head.  Couple of thoughts currently running around in my head:

• entity modes define extension to the logical model.  So for example the logical model defines a class Entity, then we'd have entity-mode-specific subclasses of that class (PojoEntity, Dom4jEntity, MapEntity).  For "pros", this would seem to allow easier pluggable extension of entity modes (aka new modes) depending of course on how these translate to Tuplizers and such.  For "cons", I am not sure what "collects" the relationship between them and the logical mode.  What I mean is that mapping (3) is slated to define the relationship between the logical model (1) and physical model (2).  But if there are really multiple logical models (one per entity mode) this gets ugly).
• basic delegation between logical model and entity mode (aka Entity would contain a collection of its various entity modes and each entity mode representation would have ref to the Entity).
• open to any other suggestions...