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();

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.