javadoc about XML format mappings

This commit is contained in:
Gavin King 2022-01-29 00:16:34 +01:00
parent 9a11e843e6
commit f5278ce678
8 changed files with 45 additions and 36 deletions

View File

@ -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

View File

@ -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()},

View File

@ -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
*/

View File

@ -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,29 +116,28 @@ 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 {
final Enumeration<JarEntry> entries = jarFile.entries();
while ( entries.hasMoreElements() ) {
final JarEntry jarEntry = entries.nextElement();
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 ) {
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") ) {
JaxbLogger.JAXB_LOGGER.tracef( "Found hbm.xml mapping in jar : %s", jarEntry.getName() );
consumer.accept( new JarFileEntryXmlSource( origin, jarFile, jarEntry ) );
}
}
}

View File

@ -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 {

View File

@ -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.
*

View File

@ -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 ) );
}

View File

@ -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 {