Process for building SessionFactory

gistfile1.java

Build ServiceRegistry
---------------------

   Map config = ...;

A) 

   ServiceRegistry serviceRegistry = 
     new ServiceRegistryBuilder( config )
        ...
        .buildServiceRegistry();

B) 
   ServiceRegistry serviceRegistry = 
     new ServiceRegistryBuilder()
        .setConfigurationData( config )
        .setOption( Environment.SHOW_SQL, true )
        .buildServiceRegistry();

Questions:
1) Will there need to be a Jpa-specific ServiceRegistryBuilder (e.g., configured w/ 
   JPA-specific listeners?
2) Emmanuel suggested using something like the following to set the default 
   services for JPA:
     JPAWasher.wash(builder);
   GB: JPAWasher would live in a different package, so ServiceRegistryBuilder 
       would have to have public setters (maybe OK for a builder).
   EB: The other approach I tend to prefer at the moment is the JPA specific ServiceRegistryBuilder

Build MetadataSources:
----------------------

MetadataSources sources = 
         new MetadataSources( serviceRegistry )
            .addAnnotatedClass( Order.class )
            .addResource( "OrderLine.hbm.xml" )
            ...;

1) Does it make sense that MetadataSources could have some resources using 
   hibernate-mapping-4.0.xsd and others using orm_2_0.xsd?
2) Should there need to be a JpaMetadataSources?
   EB very likely dues to the way we parse persistence.xml and derive metadata from it

Build Metadata:
---------------

A) Metadata metadata =
        sources
           .getMetadataBuilder()
              .setNamingStrategy( namingStrategy )
              ... // other config stuff
              .buildMetadata();

B) Metadata metadata = 
        new MetadataBuilder()
            .setNamingStrategy( namingStrategy )
            ... // other config stuff
            .buildMetadata( sources );

   (makes it absolutely clear that the namingStrategy is 
    associated with the MetadataBuilder, not w/ MetadataSources)
   EB note that B does not allow us to do chaining methods when building the API (one need to nest).

C) Metadata metadata = sources.buildMetadata( new NamingStrategy() );

   (this is OK if there's no need for a MetadataBuilder)
   (also allows metadata to be built from the same source multiple 
    times using different naming strategies)

D) 
   //if you don't need a custom naming strategy
   Metadata metadata = sources.buildMetadata();
   
   //if you need a custom naming strategy
   Metadata metadata = sources
                         .withOptions()
                           .setNamingStrategy( new NamingStrategy {} )
                         .buildMetadata();
The benefit of D over the other approaches are:
 - it's as concise if you don't need a custom naming strategy (90% of users)
 - it leaves the doors open to more options like NamingStrategy for the future without adding overloaded methods or constructors. And the API is a bit more self descriptive that with the constructor or overloaded buildMetadata().

1) Would there be a need for a JpaMetadataBuilder? If there is a 
JpaMetadataSources or some other way to indicate "jpa" sources, then 
A) could get the JpaMetadataBuilder.
  EB yes we need a JPAMetadataBuilder to return a version of Metadata object that can build EMFs

Build SessionFactory:
---------------------

SessionFactory sf = metadata.buildSessionFactory();

I'll comment on the sections individually first to work around my ADD...

Build ServiceRegistry

Well listeners are a tad different. They should be handled by an Integrator. The question of whether it is auto processed is separate. Whatever we decide for that, the listeners should be applied by Integrator.

(A) and (B) are not mutually exclusive. Take a look at the actual ServiceRegistryBuilder code...

I think the rest really depends on a few things. First, do we keep a notion similar to EJB3Configuration? To me it has the same schizophrenia that Configuration had. In terms of the metadata, that can already all be handled (and is in fact) with MetadataSources and the builder (the builder would need to know the notion of "order/precedence"). Everything else falls into "configuration" and services.

So is the thought to just drop EJB3Configuration and use MetadataSources + JpaServiceRegsitryBuilder ? I like that idea actually. Is the current recommendation for users to use EJB3Configuration? Or is it to use the JPA-defined bootstrapping methods?

Build MetadataSources:

MetadataSources is strictly mapping information. persistence.xml, just like hibernate.cfg.xml, is more a configuration/service concern. Yes it names mapping classes/files, but thats just information needing to be applied to MetadataSources, imo.

As for MetadataSources -> Metadata, I think we will need a builder. Another option for that process is the notion of precedence. So we now have at least 2. I do however like the "straight" MetadataSources.buildMetadata() for the "default" case.

Build SessionFactory:

There was a comment about building a EMF and needing a custom Metadata or MetadataSources or MetadataBuilder for this purpose. I do not think it is needed. Nor, personally, do I think it is desirable.

Really this gets to the age-old hope we have had to be able to simply build a EMF from a SF+config. Maybe this is even more achievable today with this split we have:

EntityManagerFactory emf = sources.buildMetadata().buildEntitymanagerFactory();

This implies:

interface Metadata {
    public SessionFactory buildSessionFactory();
    public EntityManagerFactory buildEntityManagerFactory();
    ...
}

Overall some really great thoughts here! Thanks guys!

Build Metadata:

I'd also suggest E)

//if you don't need a custom naming strategy
   Metadata metadata = sources.buildMetadata();

   //if you need a custom naming strategy
   Metadata metadata = sources
                         .with( new NamingStrategy {} )
                         .buildMetadata();

This would require duplicate methods in MetadataSources and the implied Options class that withOptions() returns (so more work and maintenance concerns for us), but it would make things smoother for the user. I removed NamingStrategy from the method name since the parameter's type already distinguishes the method from other with methods.