HHH-6447 - Develop shared binding creation approach

hibernate-core/src/main/java/org/hibernate/cfg/HbmBinder.java

@@ -1150,7 +1150,7 @@ public final class HbmBinder {
 			mappings.addColumnBinding( logicalName, column, table );
 			/* TODO: joinKeyColumnName & foreignKeyColumnName should be called either here or at a
 			 * slightly higer level in the stack (to get all the information we need)
-			 * Right now HbmSourceProcessorImpl does not support the
+			 * Right now HbmMetadataSourceProcessorImpl does not support the
 			 */
 			simpleValue.getTable().addColumn( column );
 			simpleValue.addColumn( column );

hibernate-core/src/main/java/org/hibernate/cfg/ToOneFkSecondPass.java

@@ -115,7 +115,7 @@ public class ToOneFkSecondPass extends FkSecondPass {
 			BinderHelper.createSyntheticPropertyReference( columns, ref, null, manyToOne, false, mappings );
 			TableBinder.bindFk( ref, null, columns, manyToOne, unique, mappings );
 			/*
-			 * HbmSourceProcessorImpl does this only when property-ref != null, but IMO, it makes sense event if it is null
+			 * HbmMetadataSourceProcessorImpl does this only when property-ref != null, but IMO, it makes sense event if it is null
 			 */
 			if ( !manyToOne.isIgnoreNotFound() ) manyToOne.createPropertyRefConstraints( persistentClasses );
 		}

hibernate-core/src/main/java/org/hibernate/cfg/annotations/PropertyBinder.java

@@ -172,7 +172,7 @@ public class PropertyBinder {
 
 	private Property makePropertyAndValue() {
 		validateBind();
-        LOG.debugf("SourceProcessor property %s with lazy=%s", name, lazy);
+        LOG.debugf("MetadataSourceProcessor property %s with lazy=%s", name, lazy);
 		String containerClassName = holder == null ?
 				null :
 				holder.getClassName();

hibernate-core/src/main/java/org/hibernate/metamodel/Metadata.java

@@ -47,7 +47,7 @@ public interface Metadata {
 	 * Exposes the options used to produce a {@link Metadata} instance.
 	 */
 	public static interface Options {
-		public SourceProcessingOrder getSourceProcessingOrder();
+		public MetadataSourceProcessingOrder getMetadataSourceProcessingOrder();
 		public NamingStrategy getNamingStrategy();
 		public SharedCacheMode getSharedCacheMode();
 		public AccessType getDefaultAccessType();

hibernate-core/src/main/java/org/hibernate/metamodel/MetadataBuilder.java

@@ -35,7 +35,7 @@ import org.hibernate.cfg.NamingStrategy;
 public interface MetadataBuilder {
 	public MetadataBuilder with(NamingStrategy namingStrategy);
 
-	public MetadataBuilder with(SourceProcessingOrder sourceProcessingOrder);
+	public MetadataBuilder with(MetadataSourceProcessingOrder metadataSourceProcessingOrder);
 
 	public MetadataBuilder with(SharedCacheMode cacheMode);
 

hibernate-core/src/main/java/org/hibernate/metamodel/MetadataSourceProcessingOrder.java

@@ -29,7 +29,7 @@ package org.hibernate.metamodel;
  *
  * @author Steve Ebersole
  */
-public enum SourceProcessingOrder {
+public enum MetadataSourceProcessingOrder {
 	ANNOTATIONS_FIRST,
 	HBM_FIRST
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/MetadataSourceProcessor.java

@@ -32,7 +32,7 @@ import org.hibernate.metamodel.MetadataSources;
  *
  * @author Steve Ebersole
  */
-public interface SourceProcessor {
+public interface MetadataSourceProcessor {
 	/**
 	 * Prepare for processing the given sources.
 	 *

hibernate-core/src/main/java/org/hibernate/metamodel/source/annotations/AnnotationMetadataSourceProcessorImpl.java

@@ -41,7 +41,7 @@ import org.hibernate.metamodel.domain.Hierarchical;
 import org.hibernate.metamodel.domain.NonEntity;
 import org.hibernate.metamodel.domain.Superclass;
 import org.hibernate.metamodel.source.MetadataImplementor;
-import org.hibernate.metamodel.source.SourceProcessor;
+import org.hibernate.metamodel.source.MetadataSourceProcessor;
 import org.hibernate.metamodel.source.annotation.jaxb.XMLEntityMappings;
 import org.hibernate.metamodel.source.annotations.entity.ConfiguredClassHierarchy;
 import org.hibernate.metamodel.source.annotations.entity.ConfiguredClassType;
@@ -67,13 +67,13 @@ import org.hibernate.service.classloading.spi.ClassLoaderService;
  * @author Hardy Ferentschik
  * @author Steve Ebersole
  */
-public class AnnotationProcessor implements SourceProcessor {
-	private static final Logger LOG = Logger.getLogger( AnnotationProcessor.class );
+public class AnnotationMetadataSourceProcessorImpl implements MetadataSourceProcessor {
+	private static final Logger LOG = Logger.getLogger( AnnotationMetadataSourceProcessorImpl.class );
 
 	private final MetadataImplementor metadata;
 	private AnnotationBindingContext bindingContext;
 
-	public AnnotationProcessor(MetadataImpl metadata) {
+	public AnnotationMetadataSourceProcessorImpl(MetadataImpl metadata) {
 		this.metadata = metadata;
 	}
 

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/AttributeSource.java

@@ -24,6 +24,8 @@
 package org.hibernate.metamodel.source.binder;
 
 /**
+ * Contract for sources of persistent attribute descriptions.
+ *
  * @author Steve Ebersole
  */
 public interface AttributeSource {
@@ -34,7 +36,17 @@ public interface AttributeSource {
 	 */
 	public String getName();
 
+	/**
+	 * Is this a singular attribute?  Specifically, can it be cast to {@link SingularAttributeSource}?
+	 *
+	 * @return {@code true} indicates this is castable to {@link SingularAttributeSource}; {@code false} otherwise.
+	 */
 	public boolean isSingular();
 
+	/**
+	 * Obtain the meta-attribute sources associated with this attribute.
+	 *
+	 * @return The meta-attribute sources.
+	 */
 	public Iterable<MetaAttributeSource> metaAttributes();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/AttributeSourceContainer.java

@@ -24,8 +24,16 @@
 package org.hibernate.metamodel.source.binder;
 
 /**
+ * Contract for a container of {@link AttributeSource} references.  Both entities and components contain
+ * attributes.
+ *
  * @author Steve Ebersole
  */
 public interface AttributeSourceContainer {
+	/**
+	 Obtain this container's attribute sources.
+	 *
+	 * @return TYhe attribute sources.
+	 */
 	public Iterable<AttributeSource> attributeSources();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/Binder.java

@@ -57,6 +57,10 @@ import org.hibernate.persister.entity.EntityPersister;
 import org.hibernate.tuple.entity.EntityTuplizer;
 
 /**
+ * The common binder shared between annotations and {@code hbm.xml} processing.
+ * <p/>
+ * The API consists of {@link #Binder} and {@link #processEntityHierarchy}
+ *
  * @author Steve Ebersole
  */
 public class Binder {
@@ -72,6 +76,11 @@ public class Binder {
 		this.processedEntityNames = processedEntityNames;
 	}
 
+	/**
+	 * Process an entity hierarchy.
+	 *
+	 * @param entityHierarchy THe hierarchy to process.
+	 */
 	public void processEntityHierarchy(EntityHierarchy entityHierarchy) {
 		currentInheritanceType = entityHierarchy.getHierarchyInheritanceType();
 		EntityBinding rootEntityBinding = createEntityBinding( entityHierarchy.getRootEntitySource(), null );
@@ -546,7 +555,7 @@ public class Binder {
 	}
 
 	private org.hibernate.metamodel.relational.Value makeValue(
-			RelationValueMetadataSource relationValueMetadataSource,
+			RelationalValueSourceContainer relationalValueSourceContainer,
 			SimpleAttributeBinding attributeBinding) {
 
 		// todo : to be completely correct, we need to know which table the value belongs to.
@@ -554,9 +563,9 @@ public class Binder {
 		//		For now, just use the entity's base table.
 		final TableSpecification table = attributeBinding.getEntityBinding().getBaseTable();
 
-		if ( relationValueMetadataSource.relationalValueSources().size() > 0 ) {
+		if ( relationalValueSourceContainer.relationalValueSources().size() > 0 ) {
 			List<SimpleValue> values = new ArrayList<SimpleValue>();
-			for ( RelationalValueSource valueSource : relationValueMetadataSource.relationalValueSources() ) {
+			for ( RelationalValueSource valueSource : relationalValueSourceContainer.relationalValueSources() ) {
 				if ( ColumnSource.class.isInstance( valueSource ) ) {
 					final ColumnSource columnSource = ColumnSource.class.cast( valueSource );
 					final Column column = table.locateOrCreateColumn( columnSource.getName() );

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/ColumnSource.java

@@ -27,29 +27,86 @@ import org.hibernate.metamodel.relational.Datatype;
 import org.hibernate.metamodel.relational.Size;
 
 /**
+ * Contract for source information pertaining to a column definition.
+ *
  * @author Steve Ebersole
  */
 public interface ColumnSource extends RelationalValueSource {
+	/**
+	 * Obtain the name of the column.
+	 *
+	 * @return The name of the column.  Can be {@code null}, in which case a naming strategy is applied.
+	 */
 	public String getName();
 
-	public boolean isNullable();
-
-	public String getDefaultValue();
-
-	public String getSqlType();
-
-	public Datatype getDatatype();
-
-	public Size getSize();
-
+	/**
+	 * A SQL fragment to apply to the column value on read.
+	 *
+	 * @return The SQL read fragment
+	 */
 	public String getReadFragment();
 
+	/**
+	 * A SQL fragment to apply to the column value on write.
+	 *
+	 * @return The SQL write fragment
+	 */
 	public String getWriteFragment();
 
+	/**
+	 * Is this column nullable?
+	 *
+	 * @return {@code true} indicates it is nullable; {@code false} non-nullable.
+	 */
+	public boolean isNullable();
+
+	/**
+	 * Obtain a specified default value for the column
+	 *
+	 * @return THe column default
+	 */
+	public String getDefaultValue();
+
+	/**
+	 * Obtain the free-hand definition of the column's type.
+	 *
+	 * @return The free-hand column type
+	 */
+	public String getSqlType();
+
+	/**
+	 * The deduced (and dialect convertible) type for this column
+	 *
+	 * @return The column's SQL data type.
+	 */
+	public Datatype getDatatype();
+
+	/**
+	 * Obtain the specified column size.
+	 *
+	 * @return The column size.
+	 */
+	public Size getSize();
+
+	/**
+	 * Is this column unique?
+	 *
+	 * @return {@code true} indicates it is unique; {@code false} non-unique.
+	 */
 	public boolean isUnique();
 
+	/**
+	 * Obtain the specified check constraint condition
+	 *
+	 * @return Check constraint condition
+	 */
 	public String getCheckCondition();
 
+	/**
+	 * Obtain the specified SQL comment
+	 *
+	 * @return SQL comment
+	 */
 	public String getComment();
 
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/DerivedValueSource.java

@@ -24,8 +24,15 @@
 package org.hibernate.metamodel.source.binder;
 
 /**
+ * Contract describing source of a derived value (formula).
+ *
  * @author Steve Ebersole
  */
 public interface DerivedValueSource extends RelationalValueSource {
+	/**
+	 * Obtain the expression used to derive the value.
+	 *
+	 * @return The derived value expression.
+	 */
 	public String getExpression();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/EntityHierarchy.java

@@ -31,6 +31,19 @@ import org.hibernate.metamodel.binding.InheritanceType;
  * @author Steve Ebersole
  */
 public interface EntityHierarchy {
+	/**
+	 * The inheritance type/strategy for the hierarchy.
+	 * <p/>
+	 * NOTE : The entire hierarchy must comply with the same inheritance strategy.
+	 *
+	 * @return The inheritance type.
+	 */
 	public InheritanceType getHierarchyInheritanceType();
+
+	/**
+	 * Obtain the hierarchy's root entity.
+	 *
+	 * @return THe root entity.
+	 */
 	public RootEntitySource getRootEntitySource();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/EntitySource.java

@@ -30,36 +30,158 @@ import org.hibernate.metamodel.source.LocalBindingContext;
 import org.hibernate.metamodel.source.Origin;
 
 /**
+ * Contract describing source of an entity
+ *
  * @author Steve Ebersole
  */
 public interface EntitySource extends SubclassEntityContainer, AttributeSourceContainer {
+	/**
+	 * Obtain the origin of this source.
+	 *
+	 * @return The origin of this source.
+	 */
 	public Origin getOrigin();
+
+	/**
+	 * Obtain the binding context local to this entity source.
+	 *
+	 * @return The local binding context
+	 */
 	public LocalBindingContext getBindingContext();
 
+	/**
+	 * Obtain the entity name
+	 *
+	 * @return The entity name
+	 */
 	public String getEntityName();
+
+	/**
+	 * Obtain the name of the entity {@link Class}
+	 *
+	 * @return THe entity class name
+	 */
 	public String getClassName();
+
+	/**
+	 * Obtain the JPA name of the entity
+	 *
+	 * @return THe JPA-specific entity name
+	 */
 	public String getJpaEntityName();
 
+	/**
+	 * Obtain the primary table for this entity.
+	 *
+	 * @return The primary table.
+	 */
 	public TableSource getPrimaryTable();
 
-    public boolean isAbstract();
-    public boolean isLazy();
-    public String getProxy();
-    public int getBatchSize();
-    public boolean isDynamicInsert();
-    public boolean isDynamicUpdate();
-    public boolean isSelectBeforeUpdate();
-
+	/**
+	 * Obtain the name of a custom tuplizer class to be used.
+	 *
+	 * @return The custom tuplizer class name
+	 */
 	public String getCustomTuplizerClassName();
+
+	/**
+	 * Obtain the name of a custom persister class to be used.
+	 *
+	 * @return The custom persister class name
+	 */
     public String getCustomPersisterClassName();
 
+	/**
+	 * Is this entity lazy (proxyable)?
+	 *
+	 * @return {@code true} indicates the entity is lazy; {@code false} non-lazy.
+	 */
+    public boolean isLazy();
+
+	/**
+	 * For {@link #isLazy() lazy} entities, obtain the interface to use in constructing its proxies.
+	 *
+	 * @return The proxy interface name
+	 */
+    public String getProxy();
+
+	/**
+	 * Obtain the batch-size to be applied when initializing proxies of this entity.
+	 *
+	 * @return THe batch-size.
+	 */
+    public int getBatchSize();
+
+	/**
+	 * Is the entity abstract?
+	 * <p/>
+	 * The implication is whether the entity maps to a database table.
+	 *
+	 * @return {@code true} indicates the entity is abstract; {@code false} non-abstract.
+	 */
+    public boolean isAbstract();
+
+	/**
+	 * Did the source specify dynamic inserts?
+	 *
+	 * @return {@code true} indicates dynamic inserts will be used; {@code false} otherwise.
+	 */
+    public boolean isDynamicInsert();
+
+	/**
+	 * Did the source specify dynamic updates?
+	 *
+	 * @return {@code true} indicates dynamic updates will be used; {@code false} otherwise.
+	 */
+    public boolean isDynamicUpdate();
+
+	/**
+	 * Did the source specify to perform selects to decide whether to perform (detached) updates?
+	 *
+	 * @return {@code true} indicates selects will be done; {@code false} otherwise.
+	 */
+    public boolean isSelectBeforeUpdate();
+
+	/**
+	 * Obtain the name of a named-query that will be used for loading this entity
+	 *
+	 * @return THe custom loader query name
+	 */
 	public String getCustomLoaderName();
+
+	/**
+	 * Obtain the custom SQL to be used for inserts for this entity
+	 *
+	 * @return The custom insert SQL
+	 */
 	public CustomSQL getCustomSqlInsert();
+
+	/**
+	 * Obtain the custom SQL to be used for updates for this entity
+	 *
+	 * @return The custom update SQL
+	 */
 	public CustomSQL getCustomSqlUpdate();
+
+	/**
+	 * Obtain the custom SQL to be used for deletes for this entity
+	 *
+	 * @return The custom delete SQL
+	 */
 	public CustomSQL getCustomSqlDelete();
 
+	/**
+	 * Obtain any additional table names on which to synchronize (auto flushing) this entity.
+	 *
+	 * @return Additional synchronized table names.
+	 */
 	public List<String> getSynchronizedTableNames();
 
+	/**
+	 * Obtain the meta-attribute sources associated with this entity.
+	 *
+	 * @return The meta-attribute sources.
+	 */
 	public Iterable<MetaAttributeSource> metaAttributes();
 
 //	public List<XMLFetchProfileElement> getFetchProfile();

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/IdentifierAttributeSource.java

@@ -1,31 +0,0 @@
-/*
- * Hibernate, Relational Persistence for Idiomatic Java
- *
- * Copyright (c) 2011, Red Hat Inc. or third-party contributors as
- * indicated by the @author tags or express copyright attribution
- * statements applied by the authors.  All third-party contributions are
- * distributed under license by Red Hat Inc.
- *
- * This copyrighted material is made available to anyone wishing to use, modify,
- * copy, or redistribute it subject to the terms and conditions of the GNU
- * Lesser General Public License, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
- * for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this distribution; if not, write to:
- * Free Software Foundation, Inc.
- * 51 Franklin Street, Fifth Floor
- * Boston, MA  02110-1301  USA
- */
-package org.hibernate.metamodel.source.binder;
-
-/**
- * @author Steve Ebersole
- */
-public interface IdentifierAttributeSource {
-
-}

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/IdentifierSource.java

@@ -24,14 +24,33 @@
 package org.hibernate.metamodel.source.binder;
 
 /**
+ * Contract describing source of identifier information for the entity.
+ * 
  * @author Steve Ebersole
  */
 public interface IdentifierSource {
 	public static enum Nature {
+		/**
+		 * A single, simple identifier.  Equivalent of an {@code <id/>} mapping or a single {@code @Id}
+		 * annotation.  Indicates the {@link IdentifierSource} is castable to {@link SimpleIdentifierSource}.
+		 */
 		SIMPLE,
+		/**
+		 * What we used to term an "embedded composite identifier", which is not to be confused with the JPA
+		 * term embedded.  Specifically a composite id where there is no component class, though there may be an
+		 * {@code @IdClass}.
+		 */
 		COMPOSITE,
+		/**
+		 * Composite identifier with an actual component class used to aggregate the individual attributes
+		 */
 		AGGREGATED_COMPOSITE
 	}
 
+	/**
+	 * Obtain the nature of this identifier source.
+	 *
+	 * @return The identifier source's nature.
+	 */
 	public Nature getNature();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/RelationalValueSource.java

@@ -24,7 +24,12 @@
 package org.hibernate.metamodel.source.binder;
 
 /**
+ * Unifying interface for {@link ColumnSource} and {@link DerivedValueSource}.
+ *
  * @author Steve Ebersole
+ * 
+ * @see ColumnSource
+ * @see DerivedValueSource
  */
 public interface RelationalValueSource {
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/RelationalValueSourceContainer.java

@@ -26,8 +26,15 @@ package org.hibernate.metamodel.source.binder;
 import java.util.List;
 
 /**
+ * Contract for a container of {@link RelationalValueSource} references.
+ *
  * @author Steve Ebersole
  */
-public interface RelationValueMetadataSource {
+public interface RelationalValueSourceContainer {
+	/**
+	 * Obtain the contained {@link RelationalValueSource} references.
+	 *
+	 * @return The contained {@link RelationalValueSource} references.
+	 */
 	public List<RelationalValueSource> relationalValueSources();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/RootEntitySource.java

@@ -23,25 +23,81 @@
  */
 package org.hibernate.metamodel.source.binder;
 
-import java.util.List;
-
 import org.hibernate.EntityMode;
 import org.hibernate.engine.OptimisticLockStyle;
 import org.hibernate.metamodel.binding.Caching;
 
 /**
+ * Contract for the entity that is the root of an inheritance hierarchy.
+ *
  * @author Steve Ebersole
  */
 public interface RootEntitySource extends EntitySource {
+	/**
+	 * Obtain source information about this entity's identifier.
+	 *
+	 * @return Identifier source information.
+	 */
 	public IdentifierSource getIdentifierSource();
+
+	/**
+	 * Obtain the source information about the attribute used for versioning.
+	 *
+	 * @return
+	 */
 	public SingularAttributeSource getVersioningAttributeSource();
+
+	// todo : I think this needs to go away
 	public SingularAttributeSource getDiscriminatorAttributeSource();
 
+	/**
+	 * Obtain the entity mode for this entity.
+	 * <p/>
+	 * todo : I think this should probably move to EntityHierarchy.
+	 *
+	 * @return The entity mode.
+	 */
 	public EntityMode getEntityMode();
+
+	/**
+	 * Is this root entity mutable?
+	 *
+	 * @return {@code true} indicates mutable; {@code false} non-mutable.
+	 */
 	public boolean isMutable();
+
+	/**
+	 * Should explicit polymorphism (querying) be applied to this entity?
+	 *
+	 * @return {@code true} indicates explicit polymorphism; {@code false} implicit.
+	 */
 	public boolean isExplicitPolymorphism();
+
+	/**
+	 * Obtain the specified extra where condition to be applied to this entity.
+	 *
+	 * @return The extra where condition
+	 */
 	public String getWhere();
+
+	/**
+	 * Obtain the row-id name for this entity
+	 *
+	 * @return The row-id name
+	 */
 	public String getRowId();
+
+	/**
+	 * Obtain the optimistic locking style for this entity.
+	 *
+	 * @return The optimistic locking style.
+	 */
 	public OptimisticLockStyle getOptimisticLockStyle();
+
+	/**
+	 * Obtain the caching configuration for this entity.
+	 *
+	 * @return The caching configuration.
+	 */
 	public Caching getCaching();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/SimpleIdentifierSource.java

@@ -26,9 +26,22 @@ package org.hibernate.metamodel.source.binder;
 import org.hibernate.metamodel.binding.IdGenerator;
 
 /**
+ * Contract describing source of a simple identifier mapping.
+ *
  * @author Steve Ebersole
  */
 public interface SimpleIdentifierSource extends IdentifierSource {
+	/**
+	 * Obtain the source descriptor for the identifier attribute.
+	 *
+	 * @return The identifier attribute source.
+	 */
 	public SingularAttributeSource getIdentifierAttributeSource();
+
+	/**
+	 * Obtain the identifier generator source.
+	 *
+	 * @return The generator source.
+	 */
 	public IdGenerator getIdentifierGeneratorDescriptor();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/SingularAttributeSource.java

@@ -23,8 +23,6 @@
  */
 package org.hibernate.metamodel.source.binder;
 
-import java.util.List;
-
 import org.hibernate.engine.spi.CascadeStyle;
 import org.hibernate.mapping.PropertyGeneration;
 
@@ -33,7 +31,7 @@ import org.hibernate.mapping.PropertyGeneration;
  *
  * @author Steve Ebersole
  */
-public interface SingularAttributeSource extends AttributeSource, RelationValueMetadataSource {
+public interface SingularAttributeSource extends AttributeSource, RelationalValueSourceContainer {
 	/**
 	 * Determine whether this is a virtual attribute or whether it physically exists on the users domain model.
 	 *

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/TableSource.java

@@ -24,10 +24,29 @@
 package org.hibernate.metamodel.source.binder;
 
 /**
+ * Contract describing source of table information
+ *
  * @author Steve Ebersole
  */
 public interface TableSource {
+	/**
+	 * Obtain the supplied schema name
+	 *
+	 * @return The schema name.  If {@code null}, the binder will apply the default.
+	 */
 	public String getExplicitSchemaName();
+
+	/**
+	 * Obtain the supplied catalog name
+	 *
+	 * @return The catalog name.  If {@code null}, the binder will apply the default.
+	 */
 	public String getExplicitCatalogName();
+
+	/**
+	 * Obtain the supplied table name.
+	 *
+	 * @return The table name.
+	 */
 	public String getExplicitTableName();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/binder/ToOneAttributeSource.java

@@ -24,9 +24,24 @@
 package org.hibernate.metamodel.source.binder;
 
 /**
+ * Further contract for sources of {@code *-to-one} style associations.
+ *
  * @author Steve Ebersole
  */
 public interface ToOneAttributeSource extends SingularAttributeSource {
+	/**
+	 * Obtain the name of the referenced entity.
+	 *
+	 * @return The name of the referenced entity
+	 */
 	public String getReferencedEntityName();
+
+	/**
+	 * Obtain the name of the referenced attribute.  Typically the reference is built based on the identifier
+	 * attribute of the {@link #getReferencedEntityName() referenced entity}, but this value allows using a different
+	 * attribute instead.
+	 *
+	 * @return The name of the referenced attribute; {@code null} indicates the identifier attribute.
+	 */
 	public String getReferencedEntityAttributeName();
 }

hibernate-core/src/main/java/org/hibernate/metamodel/source/hbm/HbmMetadataSourceProcessorImpl.java

@@ -28,23 +28,23 @@ import java.util.List;
 
 import org.hibernate.metamodel.MetadataSources;
 import org.hibernate.metamodel.source.MetadataImplementor;
-import org.hibernate.metamodel.source.SourceProcessor;
+import org.hibernate.metamodel.source.MetadataSourceProcessor;
 import org.hibernate.metamodel.source.binder.Binder;
 import org.hibernate.metamodel.source.internal.JaxbRoot;
 import org.hibernate.metamodel.source.hbm.jaxb.mapping.XMLHibernateMapping;
 
 /**
- * The {@link SourceProcessor} implementation responsible for processing {@code hbm.xml} sources.
+ * The {@link org.hibernate.metamodel.source.MetadataSourceProcessor} implementation responsible for processing {@code hbm.xml} sources.
  *
  * @author Steve Ebersole
  */
-public class HbmSourceProcessorImpl implements SourceProcessor {
+public class HbmMetadataSourceProcessorImpl implements MetadataSourceProcessor {
 	private final MetadataImplementor metadata;
 
 	private List<HibernateMappingProcessor> processors = new ArrayList<HibernateMappingProcessor>();
 	private List<EntityHierarchyImpl> entityHierarchies;
 
-	public HbmSourceProcessorImpl(MetadataImplementor metadata) {
+	public HbmMetadataSourceProcessorImpl(MetadataImplementor metadata) {
 		this.metadata = metadata;
 	}
 

hibernate-core/src/main/java/org/hibernate/metamodel/source/hbm/HibernateMappingProcessor.java

@@ -51,7 +51,7 @@ import org.hibernate.type.Type;
 /**
  * Responsible for processing a {@code <hibernate-mapping/>} element.  Allows processing to be coordinated across
  * all hbm files in an ordered fashion.  The order is essentially the same as defined in
- * {@link org.hibernate.metamodel.source.SourceProcessor}
+ * {@link org.hibernate.metamodel.source.MetadataSourceProcessor}
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/metamodel/source/internal/MetadataBuilderImpl.java

@@ -31,8 +31,8 @@ import org.hibernate.cfg.EJB3NamingStrategy;
 import org.hibernate.cfg.NamingStrategy;
 import org.hibernate.metamodel.Metadata;
 import org.hibernate.metamodel.MetadataBuilder;
+import org.hibernate.metamodel.MetadataSourceProcessingOrder;
 import org.hibernate.metamodel.MetadataSources;
-import org.hibernate.metamodel.SourceProcessingOrder;
 import org.hibernate.service.BasicServiceRegistry;
 import org.hibernate.service.config.spi.ConfigurationService;
 
@@ -55,8 +55,8 @@ public class MetadataBuilderImpl implements MetadataBuilder {
 	}
 
 	@Override
-	public MetadataBuilder with(SourceProcessingOrder sourceProcessingOrder) {
-		this.options.sourceProcessingOrder = sourceProcessingOrder;
+	public MetadataBuilder with(MetadataSourceProcessingOrder metadataSourceProcessingOrder) {
+		this.options.metadataSourceProcessingOrder = metadataSourceProcessingOrder;
 		return this;
 	}
 
@@ -84,7 +84,7 @@ public class MetadataBuilderImpl implements MetadataBuilder {
 	}
 
 	private static class OptionsImpl implements Metadata.Options {
-		private SourceProcessingOrder sourceProcessingOrder = SourceProcessingOrder.HBM_FIRST;
+		private MetadataSourceProcessingOrder metadataSourceProcessingOrder = MetadataSourceProcessingOrder.HBM_FIRST;
 		private NamingStrategy namingStrategy = EJB3NamingStrategy.INSTANCE;
 		private SharedCacheMode sharedCacheMode = SharedCacheMode.ENABLE_SELECTIVE;
 		private AccessType defaultCacheAccessType;
@@ -154,8 +154,8 @@ public class MetadataBuilderImpl implements MetadataBuilder {
 
 
 		@Override
-		public SourceProcessingOrder getSourceProcessingOrder() {
-			return sourceProcessingOrder;
+		public MetadataSourceProcessingOrder getMetadataSourceProcessingOrder() {
+			return metadataSourceProcessingOrder;
 		}
 
 		@Override

hibernate-core/src/main/java/org/hibernate/metamodel/source/internal/MetadataImpl.java

@@ -46,15 +46,15 @@ import org.hibernate.id.factory.DefaultIdentifierGeneratorFactory;
 import org.hibernate.id.factory.IdentifierGeneratorFactory;
 import org.hibernate.internal.CoreMessageLogger;
 import org.hibernate.internal.util.Value;
+import org.hibernate.metamodel.MetadataSourceProcessingOrder;
 import org.hibernate.metamodel.MetadataSources;
 import org.hibernate.metamodel.SessionFactoryBuilder;
-import org.hibernate.metamodel.SourceProcessingOrder;
 import org.hibernate.metamodel.source.MappingDefaults;
 import org.hibernate.metamodel.source.MetaAttributeContext;
 import org.hibernate.metamodel.source.MetadataImplementor;
-import org.hibernate.metamodel.source.SourceProcessor;
-import org.hibernate.metamodel.source.annotations.AnnotationProcessor;
-import org.hibernate.metamodel.source.hbm.HbmSourceProcessorImpl;
+import org.hibernate.metamodel.source.MetadataSourceProcessor;
+import org.hibernate.metamodel.source.annotations.AnnotationMetadataSourceProcessorImpl;
+import org.hibernate.metamodel.source.hbm.HbmMetadataSourceProcessorImpl;
 import org.hibernate.metamodel.binding.AttributeBinding;
 import org.hibernate.metamodel.binding.EntityBinding;
 import org.hibernate.metamodel.binding.FetchProfile;
@@ -123,17 +123,17 @@ public class MetadataImpl implements MetadataImplementor, Serializable {
 
 		this.mappingDefaults = new MappingDefaultsImpl();
 
-		final SourceProcessor[] sourceProcessors;
-		if ( options.getSourceProcessingOrder() == SourceProcessingOrder.HBM_FIRST ) {
-			sourceProcessors = new SourceProcessor[] {
-					new HbmSourceProcessorImpl( this ),
-					new AnnotationProcessor( this )
+		final MetadataSourceProcessor[] metadataSourceProcessors;
+		if ( options.getMetadataSourceProcessingOrder() == MetadataSourceProcessingOrder.HBM_FIRST ) {
+			metadataSourceProcessors = new MetadataSourceProcessor[] {
+					new HbmMetadataSourceProcessorImpl( this ),
+					new AnnotationMetadataSourceProcessorImpl( this )
 			};
 		}
 		else {
-			sourceProcessors = new SourceProcessor[] {
-					new AnnotationProcessor( this ),
-					new HbmSourceProcessorImpl( this )
+			metadataSourceProcessors = new MetadataSourceProcessor[] {
+					new AnnotationMetadataSourceProcessorImpl( this ),
+					new HbmMetadataSourceProcessorImpl( this )
 			};
 		}
 
@@ -157,44 +157,44 @@ public class MetadataImpl implements MetadataImplementor, Serializable {
 
 		final ArrayList<String> processedEntityNames = new ArrayList<String>();
 
-		prepare( sourceProcessors, metadataSources );
-		bindIndependentMetadata( sourceProcessors, metadataSources );
-		bindTypeDependentMetadata( sourceProcessors, metadataSources );
-		bindMappingMetadata( sourceProcessors, metadataSources, processedEntityNames );
-		bindMappingDependentMetadata( sourceProcessors, metadataSources );
+		prepare( metadataSourceProcessors, metadataSources );
+		bindIndependentMetadata( metadataSourceProcessors, metadataSources );
+		bindTypeDependentMetadata( metadataSourceProcessors, metadataSources );
+		bindMappingMetadata( metadataSourceProcessors, metadataSources, processedEntityNames );
+		bindMappingDependentMetadata( metadataSourceProcessors, metadataSources );
 
 		// todo : remove this by coordinated ordering of entity processing
 		new EntityReferenceResolver( this ).resolve();
 		new AttributeTypeResolver( this ).resolve();
 	}
 
-	private void prepare(SourceProcessor[] sourceProcessors, MetadataSources metadataSources) {
-		for ( SourceProcessor sourceProcessor : sourceProcessors ) {
-			sourceProcessor.prepare( metadataSources );
+	private void prepare(MetadataSourceProcessor[] metadataSourceProcessors, MetadataSources metadataSources) {
+		for ( MetadataSourceProcessor metadataSourceProcessor : metadataSourceProcessors ) {
+			metadataSourceProcessor.prepare( metadataSources );
 		}
 	}
 
-	private void bindIndependentMetadata(SourceProcessor[] sourceProcessors, MetadataSources metadataSources) {
-		for ( SourceProcessor sourceProcessor : sourceProcessors ) {
-			sourceProcessor.processIndependentMetadata( metadataSources );
+	private void bindIndependentMetadata(MetadataSourceProcessor[] metadataSourceProcessors, MetadataSources metadataSources) {
+		for ( MetadataSourceProcessor metadataSourceProcessor : metadataSourceProcessors ) {
+			metadataSourceProcessor.processIndependentMetadata( metadataSources );
 		}
 	}
 
-	private void bindTypeDependentMetadata(SourceProcessor[] sourceProcessors, MetadataSources metadataSources) {
-		for ( SourceProcessor sourceProcessor : sourceProcessors ) {
-			sourceProcessor.processTypeDependentMetadata( metadataSources );
+	private void bindTypeDependentMetadata(MetadataSourceProcessor[] metadataSourceProcessors, MetadataSources metadataSources) {
+		for ( MetadataSourceProcessor metadataSourceProcessor : metadataSourceProcessors ) {
+			metadataSourceProcessor.processTypeDependentMetadata( metadataSources );
 		}
 	}
 
-	private void bindMappingMetadata(SourceProcessor[] sourceProcessors, MetadataSources metadataSources, List<String> processedEntityNames) {
-		for ( SourceProcessor sourceProcessor : sourceProcessors ) {
-			sourceProcessor.processMappingMetadata( metadataSources, processedEntityNames );
+	private void bindMappingMetadata(MetadataSourceProcessor[] metadataSourceProcessors, MetadataSources metadataSources, List<String> processedEntityNames) {
+		for ( MetadataSourceProcessor metadataSourceProcessor : metadataSourceProcessors ) {
+			metadataSourceProcessor.processMappingMetadata( metadataSources, processedEntityNames );
 		}
 	}
 
-	private void bindMappingDependentMetadata(SourceProcessor[] sourceProcessors, MetadataSources metadataSources) {
-		for ( SourceProcessor sourceProcessor : sourceProcessors ) {
-			sourceProcessor.processMappingDependentMetadata( metadataSources );
+	private void bindMappingDependentMetadata(MetadataSourceProcessor[] metadataSourceProcessors, MetadataSources metadataSources) {
+		for ( MetadataSourceProcessor metadataSourceProcessor : metadataSourceProcessors ) {
+			metadataSourceProcessor.processMappingDependentMetadata( metadataSources );
 		}
 	}
 

hibernate-core/src/test/java/org/hibernate/test/legacy/Wicked.hbm.xml

@@ -3,7 +3,7 @@
 	"-//Hibernate/Hibernate Mapping DTD 3.0//EN"
 	"http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">
 
-<!-- Mapping document mainly used for testing non-reflective SourceProcessor + meta inheritance -->
+<!-- Mapping document mainly used for testing non-reflective MetadataSourceProcessor + meta inheritance -->
 <hibernate-mapping default-lazy="false">
   <meta attribute="global">global value</meta>
   <meta attribute="globalnoinherit" inherit="false">only visible at top level</meta>