javadoc about XML format mappings

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

@@ -29,14 +29,9 @@ import org.hibernate.mapping.Table;
 import org.hibernate.query.sqm.function.SqmFunctionDescriptor;
 
 /**
- * Represents the ORM model as determined from all provided mapping sources.
+ * Represents the ORM model as determined by aggregating the provided mapping sources.
  * An instance may be obtained by calling {@link MetadataSources#buildMetadata()}.
  *
- * @apiNote For the time being this is essentially a copy of the legacy
- * {@link Mapping} contract, split between reading the mapping information
- * exposed here and collecting it via
- * {@link org.hibernate.boot.spi.InFlightMetadataCollector}.
- *
  * @author Steve Ebersole
  *
  * @since 5.0

hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java

@@ -42,6 +42,9 @@ import org.w3c.dom.Document;
  * Entry point for working with sources of O/R mapping metadata, either
  * in the form of annotated classes, or as XML mapping documents.
  * <p>
+ * Note that XML mappings may be expressed using the JPA {@code orm.xml}
+ * format, or in Hibernate's legacy {@code .hbm.xml} format.
+ * <p>
  * An instance of {@code MetadataSources} may be obtained simply by
  * instantiation, using {@link #MetadataSources() new MetadataSources()}.
  * The client must register sources and then call {@link #buildMetadata()},

hibernate-core/src/main/java/org/hibernate/boot/jaxb/Origin.java

@@ -12,7 +12,7 @@ import java.util.Objects;
 
 
 /**
- * Describes the origin of an xml document
+ * Describes the origin of an XML document.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/XmlSources.java

@@ -27,7 +27,11 @@ import org.hibernate.boot.registry.classloading.spi.ClassLoaderService;
 import org.w3c.dom.Document;
 
 /**
- * Helper for building and handling {@link XmlSource} references
+ * Helper for building and handling {@link XmlSource} references.
+ * <p>
+ * An {@code XmlSource} represents an XML document containing
+ * O/R mapping metadata, either a JPA {@code orm.xml} file, or a
+ * Hibernate {@code .hbm.xml} file.
  *
  * @author Steve Ebersole
  */
@@ -112,32 +116,31 @@ public class XmlSources {
 		return new JaxpSourceXmlSource( origin, new DOMSource( document ) );
 	}
 
+	/**
+	 * Read all {@code .hbm.xml} mappings from a jar file and pass them
+	 * to the given {@link Consumer}.
+	 * <p/>
+	 * Assumes that any file named {@code *.hbm.xml} is a mapping document.
+	 * This method does not support {@code orm.xml} files!
+	 *
+	 * @param jar a jar file
+	 * @param consumer a consumer of the resulting {@linkplain XmlSource XML sources}
+	 */
 	public static void fromJar(File jar, Consumer<XmlSource> consumer) {
 		JaxbLogger.JAXB_LOGGER.tracef( "Seeking mapping documents in jar file : %s", jar.getName() );
 
 		final Origin origin = new Origin( SourceType.JAR, jar.getAbsolutePath() );
 
-		try {
-			final JarFile jarFile = new JarFile( jar );
-
-			try {
+		try ( JarFile jarFile = new JarFile(jar) ) {
 			final Enumeration<JarEntry> entries = jarFile.entries();
 			while ( entries.hasMoreElements() ) {
 				final JarEntry jarEntry = entries.nextElement();
-					if ( jarEntry.getName().endsWith( ".hbm.xml" ) ) {
+				if ( jarEntry.getName().endsWith(".hbm.xml") ) {
 					JaxbLogger.JAXB_LOGGER.tracef( "Found hbm.xml mapping in jar : %s", jarEntry.getName() );
 					consumer.accept( new JarFileEntryXmlSource( origin, jarFile, jarEntry ) );
 				}
 			}
 		}
-			finally {
-				try {
-					jarFile.close();
-				}
-				catch ( Exception ignore ) {
-				}
-			}
-		}
 		catch ( IOException e ) {
 			throw new MappingNotFoundException( e, origin );
 		}

hibernate-core/src/main/java/org/hibernate/boot/jaxb/spi/XmlSource.java

@@ -9,6 +9,12 @@ package org.hibernate.boot.jaxb.spi;
 import org.hibernate.boot.jaxb.Origin;
 
 /**
+ * An XML document containing O/R mapping metadata, either:
+ * <ul>
+ *     <li>a JPA {@code orm.xml} file, or
+ *     <li>a Hibernate {@code .hbm.xml} file.
+ * </ul>
+ *
  * @author Steve Ebersole
  */
 public abstract class XmlSource {

hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistryBuilder.java

@@ -26,10 +26,11 @@ import org.hibernate.service.ServiceRegistry;
 /**
  * Builder for {@link BootstrapServiceRegistry} instances.
  * <p>
- * An instance of this class may be obtained by instantiations, simply by
- * calling {@code new BootstrapServiceRegistryBuilder()}. Then a new
+ * An instance of this class may be obtained simply by
+ * {@linkplain #BootstrapServiceRegistryBuilder() instantiation}. Then a new
  * {@code BootstrapServiceRegistry} may be obtained by calling {@link #build()}.
  * It should be later destroyed by calling {@link #destroy(ServiceRegistry)}.
+ * Alternatively, {@linkplain #enableAutoClose() auto-close} may be enabled.
  * <p>
  * Provides a registry of services needed for most operations.
  * Manages a {@link ClassLoaderService}, a set of {@link Integrator}s, and a
@@ -51,6 +52,9 @@ public class BootstrapServiceRegistryBuilder {
 
 	private boolean autoCloseRegistry = true;
 
+	public BootstrapServiceRegistryBuilder() {
+	}
+
 	/**
 	 * Add an {@link Integrator} to be applied to the bootstrap registry.
 	 *

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

@@ -65,7 +65,7 @@ import org.hibernate.usertype.UserType;
  * under the covers.
  * <p>
  * An instance of {@code Configuration} may be obtained simply by
- * instantiation, using {@link #Configuration() new Configuration()}.
+ * {@linkplain #Configuration() instantiation}.
  * <p>
  * A {@code Configuration} may be used to aggregate:
  * <ul>
@@ -74,6 +74,9 @@ import org.hibernate.usertype.UserType;
  * <li>entity O/R mappings, defined in either {@linkplain #addAnnotatedClass
  *    annotated classes}, or {@linkplain #addFile XML mapping documents}.
  * </ul>
+ * Note that XML mappings may be expressed using the JPA {@code orm.xml}
+ * format, or in Hibernate's legacy {@code .hbm.xml} format.
+ * <p>
  * In addition, there are convenience methods for adding
  * {@link #addAttributeConverter attribute converters},
  * {@link #registerTypeContributor type contributors},
@@ -786,7 +789,7 @@ public class Configuration {
 	 *                  property types as specified by its "entity attribute"
 	 *                  parameterized type?
 	 */
-	public void addAttributeConverter(Class<? extends AttributeConverter> attributeConverterClass, boolean autoApply) {
+	public void addAttributeConverter(Class<? extends AttributeConverter<?,?>> attributeConverterClass, boolean autoApply) {
 		addAttributeConverter( new ClassBasedConverterDescriptor( attributeConverterClass, autoApply, classmateContext ) );
 	}
 

hibernate-core/src/main/java/org/hibernate/service/ServiceRegistry.java

@@ -16,14 +16,9 @@ package org.hibernate.service;
  * and
  * <li>{@linkplain org.hibernate.boot.registry.StandardServiceRegistry
  * standard service registries}, which may be obtained from a
- * {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder},
+ * {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder}.
  * </ul>
  *
- * @see org.hibernate.boot.registry.BootstrapServiceRegistry
- * @see org.hibernate.boot.registry.StandardServiceRegistry
- * @see org.hibernate.boot.registry.BootstrapServiceRegistryBuilder
- * @see org.hibernate.boot.registry.StandardServiceRegistryBuilder
- *
  * @author Steve Ebersole
  */
 public interface ServiceRegistry extends AutoCloseable {