Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

refresh Javadoc for Configuration and friends

This commit is contained in:
Gavin King 2022-01-28 17:16:46 +01:00
parent b1a09d5630
commit fb1650f789
3 changed files with 243 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java
View File

@ -7,32 +7,21 @@
package org.hibernate.boot;
import java.io.File;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.io.Serializable;
import java.net.URL;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.jar.JarFile;
import java.util.zip.ZipEntry;
import javax.xml.transform.dom.DOMSource;
import org.hibernate.HibernateException;
import org.hibernate.boot.archive.spi.InputStreamAccess;
import org.hibernate.boot.internal.MetadataBuilderImpl;
import org.hibernate.boot.jaxb.Origin;
import org.hibernate.boot.jaxb.SourceType;
import org.hibernate.boot.jaxb.internal.CacheableFileXmlSource;
import org.hibernate.boot.jaxb.internal.JarFileEntryXmlSource;
import org.hibernate.boot.jaxb.internal.JaxpSourceXmlSource;
import org.hibernate.boot.jaxb.internal.XmlSources;
import org.hibernate.boot.jaxb.spi.Binding;
import org.hibernate.boot.jaxb.spi.XmlSource;
@ -50,9 +39,12 @@ import org.hibernate.type.SerializationException;
import org.w3c.dom.Document;
/**
* Entry point into working with sources of metadata information (mapping XML, annotations). Tell Hibernate
* about sources and then call {@link #buildMetadata()}, or use {@link #getMetadataBuilder()} to customize
* how sources are processed (naming strategies, etc).
* Entry point for working with sources of O/R mapping metadata, either
* in the form of annotated classes, or as XML mapping documents.
* <p>
* A client must register sources and then call {@link #buildMetadata()},
* or use {@link #getMetadataBuilder()} to customize how the sources are
* processed (naming strategies, etc).
*
* @author Steve Ebersole
*
@ -154,8 +146,7 @@ public class MetadataSources implements Serializable {
* @return The built metadata.
*/
public MetadataBuilder getMetadataBuilder() {
MetadataBuilderImpl defaultBuilder = new MetadataBuilderImpl( this );
return getCustomBuilderOrDefault( defaultBuilder );
return getCustomBuilderOrDefault( new MetadataBuilderImpl(this) );
}
/**
@ -166,23 +157,25 @@ public class MetadataSources implements Serializable {
*/
@Deprecated
public MetadataBuilder getMetadataBuilder(StandardServiceRegistry serviceRegistry) {
MetadataBuilderImpl defaultBuilder = new MetadataBuilderImpl( this, serviceRegistry );
return getCustomBuilderOrDefault( defaultBuilder );
return getCustomBuilderOrDefault( new MetadataBuilderImpl(this, serviceRegistry ) );
}
/**
* In case a custom {@link MetadataBuilderFactory} creates a custom builder, return that one, otherwise the default
* builder.
* In case a custom {@link MetadataBuilderFactory} creates a custom builder,
* return that one, otherwise return the default builder.
*/
private MetadataBuilder getCustomBuilderOrDefault(MetadataBuilderImpl defaultBuilder) {
final ClassLoaderService cls = serviceRegistry.getService( ClassLoaderService.class );
final Collection<MetadataBuilderFactory> discoveredBuilderFactories = cls.loadJavaServices( MetadataBuilderFactory.class );
Collection<MetadataBuilderFactory> discoveredBuilderFactories =
serviceRegistry.getService( ClassLoaderService.class )
.loadJavaServices( MetadataBuilderFactory.class );
MetadataBuilder builder = null;
List<String> activeFactoryNames = null;
for ( MetadataBuilderFactory discoveredBuilderFactory : discoveredBuilderFactories ) {
final MetadataBuilder returnedBuilder = discoveredBuilderFactory.getMetadataBuilder( this, defaultBuilder );
for ( MetadataBuilderFactory discoveredBuilderFactory : discoveredBuilderFactories) {
final MetadataBuilder returnedBuilder =
discoveredBuilderFactory.getMetadataBuilder( this, defaultBuilder );
if ( returnedBuilder != null ) {
if ( activeFactoryNames == null ) {
activeFactoryNames = new ArrayList<>();
@ -203,9 +196,9 @@ public class MetadataSources implements Serializable {
}
/**
* Short-hand form of calling {@link #getMetadataBuilder()} and using its
* {@link MetadataBuilder#build()} method in cases where the application wants
* to accept the defaults.
* Shorthand form of calling {@link #getMetadataBuilder()} and using its
* {@link MetadataBuilder#build()} method in cases where the application
* wants to accept the defaults.
*
* @return The built metadata.
*/
@ -224,7 +217,7 @@ public class MetadataSources implements Serializable {
*
* @return this (for method chaining)
*/
public MetadataSources addAnnotatedClass(Class annotatedClass) {
public MetadataSources addAnnotatedClass(Class<?> annotatedClass) {
if ( annotatedClasses == null ) {
annotatedClasses = new LinkedHashSet<>();
}
@ -246,9 +239,10 @@ public class MetadataSources implements Serializable {
}
/**
* Read metadata from the annotations attached to the given class. The important
* distinction here is that the {@link Class} will not be accessed until later
* which is important for on-the-fly bytecode-enhancement
* Read metadata from the annotations attached to the given class. The
* important distinction here is that the {@link Class} will not be
* accessed until later, which is important for on-the-fly bytecode
* enhancement
*
* @param annotatedClassName The name of a class containing annotations
*
@ -322,26 +316,26 @@ public class MetadataSources implements Serializable {
}
/**
* Read a mapping as an application resource using the convention that a class named {@code foo.bar.Foo} is
* mapped by a file named {@code foo/bar/Foo.hbm.xml} which can be resolved as a classpath resource.
* Read a mapping as an application resource using the convention
* that a class named {@code foo.bar.Foo} is mapped by a file named
* {@code foo/bar/Foo.hbm.xml} which can be resolved as a classpath
* resource.
*
* @param entityClass The mapped class. Cannot be {@code null} null.
* @param entityClass The mapped class
*
* @return this (for method chaining purposes)
*
* @deprecated hbm.xml is a legacy mapping format now considered deprecated.
*/
@Deprecated
public MetadataSources addClass(Class entityClass) {
public MetadataSources addClass(Class<?> entityClass) {
if ( entityClass == null ) {
throw new IllegalArgumentException( "The specified class cannot be null" );
}
if ( LOG.isDebugEnabled() ) {
LOG.debugf( "adding resource mappings from class convention : %s", entityClass.getName() );
}
final String mappingResourceName = entityClass.getName().replace( '.', '/' ) + ".hbm.xml";
addResource( mappingResourceName );
return this;
return addResource( entityClass.getName().replace( '.', '/' ) + ".hbm.xml" );
}
/**
@ -359,9 +353,11 @@ public class MetadataSources implements Serializable {
}
/**
* Read mappings from a particular XML file
* Read mappings from a particular XML file.
* <p>
* The given path is resolved using {@link File#File(String)}.
*
* @param path The path to a file. Expected to be resolvable by {@link File#File(String)}
* @param path The path to a file
*
* @return this (for method chaining purposes)
*
@ -373,7 +369,7 @@ public class MetadataSources implements Serializable {
}
/**
* Read mappings from a particular XML file
* Read mappings from a particular XML file.
*
* @param file The reference to the XML file
*
@ -387,9 +383,10 @@ public class MetadataSources implements Serializable {
}
/**
* Add XML mapping bindings created from an arbitrary source by the {@linkplain #getXmlMappingBinderAccess() binder}.
* Add XML mapping bindings created from an arbitrary source by the
* {@linkplain #getXmlMappingBinderAccess() binder}.
*
* @param binding The binding.
* @param binding The binding
*
* @return this (for method chaining purposes)
*/
@ -399,9 +396,11 @@ public class MetadataSources implements Serializable {
}
/**
* See {@link #addCacheableFile(File)} for description
* Add a {@link #addCacheableFile(File) cached mapping file}.
* <p>
* The given path is resolved using {@link File#File(String)}.
*
* @param path The path to a file. Expected to be resolvable by {@link File#File(String)}
* @param path The path to a file
*
* @return this (for method chaining purposes)
*
@ -413,9 +412,11 @@ public class MetadataSources implements Serializable {
}
/**
* See {@link #addCacheableFile(File)} for description
* Add a {@link #addCacheableFile(File) cached mapping file}.
* <p>
* The given path is resolved using {@link File#File(String)}.
*
* @param path The path to a file. Expected to be resolvable by {@link File#File(String)}
* @param path The path to a file
*
* @return this (for method chaining purposes)
*
@ -427,13 +428,14 @@ public class MetadataSources implements Serializable {
}
/**
* Add a cached mapping file. A cached file is a serialized representation of the DOM structure of a
* particular mapping. It is saved from a previous call as a file with the name {@code {xmlFile}.bin}
* where {@code {xmlFile}} is the name of the original mapping file.
* Add a cached mapping file. A cached file is a serialized representation of
* the DOM structure of a particular mapping. It is saved from a previous call
* as a file with the name {@code {xmlFile}.bin} where {@code {xmlFile}} is the
* name of the original mapping file.
* </p>
* If a cached {@code {xmlFile}.bin} exists and is newer than {@code {xmlFile}}, the {@code {xmlFile}.bin}
* file will be read directly. Otherwise {@code {xmlFile}} is read and then serialized to {@code {xmlFile}.bin} for
* use the next time.
* If a cached {@code {xmlFile}.bin} exists and is newer than {@code {xmlFile}},
* the {@code {xmlFile}.bin} file will be read directly. Otherwise {@code {xmlFile}}
* is read and then serialized to {@code {xmlFile}.bin} for use the next time.
*
* @param file The cacheable mapping file to be added, {@code {xmlFile}} in above discussion.
*
@ -444,13 +446,14 @@ public class MetadataSources implements Serializable {
}
/**
* Add a cached mapping file. A cached file is a serialized representation of the DOM structure of a
* particular mapping. It is saved from a previous call as a file with the name {@code {xmlFile}.bin}
* where {@code {xmlFile}} is the name of the original mapping file.
* Add a cached mapping file. A cached file is a serialized representation of
* the DOM structure of a particular mapping. It is saved from a previous call
* as a file with the name {@code {xmlFile}.bin} where {@code {xmlFile}} is the
* name of the original mapping file.
* </p>
* If a cached {@code {xmlFile}.bin} exists and is newer than {@code {xmlFile}}, the {@code {xmlFile}.bin}
* file will be read directly. Otherwise {@code {xmlFile}} is read and then serialized to {@code {xmlFile}.bin} for
* use the next time.
* If a cached {@code {xmlFile}.bin} exists and is newer than {@code {xmlFile}},
* the {@code {xmlFile}.bin} file will be read directly. Otherwise {@code {xmlFile}}
* is read and then serialized to {@code {xmlFile}.bin} for use the next time.
*
* @param file The cacheable mapping file to be added, {@code {xmlFile}} in above discussion.
*
@ -466,15 +469,15 @@ public class MetadataSources implements Serializable {
/**
* <b>INTENDED FOR TESTSUITE USE ONLY!</b>
* <p/>
* Much like {@link #addCacheableFile(File)} except that here we will fail immediately if
* the cache version cannot be found or used for whatever reason
* Much like {@link #addCacheableFile(File)} except that here we will fail
* immediately if the cache version cannot be found or used for whatever reason.
*
* @param file The xml file, not the bin!
*
* @return The dom "deserialized" from the cached file.
*
* @throws SerializationException Indicates a problem deserializing the cached dom tree
* @throws FileNotFoundException Indicates that the cached file was not found or was not usable.
* @throws MappingNotFoundException Indicates that the cached file was not found or was not usable.
*/
public MetadataSources addCacheableFileStrictly(File file) throws SerializationException {
final XmlSource xmlSource = XmlSources.fromCacheableFile( file, true );
@ -486,15 +489,15 @@ public class MetadataSources implements Serializable {
/**
* <b>INTENDED FOR TESTSUITE USE ONLY!</b>
* <p/>
* Much like {@link #addCacheableFile(File)} except that here we will fail immediately if
* the cache version cannot be found or used for whatever reason
* Much like {@link #addCacheableFile(File)} except that here we will fail
* immediately if the cache version cannot be found or used for whatever reason.
*
* @param file The xml file, not the bin!
*
* @return The dom "deserialized" from the cached file.
*
* @throws SerializationException Indicates a problem deserializing the cached dom tree
* @throws FileNotFoundException Indicates that the cached file was not found or was not usable.
* @throws MappingNotFoundException Indicates that the cached file was not found or was not usable.
*/
public MetadataSources addCacheableFileStrictly(File file, File cacheDir) throws SerializationException {
final XmlSource xmlSource = XmlSources.fromCacheableFile( file, cacheDir, true );

106
hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistryBuilder.java
View File

@ -29,6 +29,8 @@ import org.hibernate.service.StandardServiceInitiators;
import org.hibernate.service.internal.ProvidedService;
import org.hibernate.service.spi.ServiceContributor;
import static org.hibernate.boot.cfgxml.spi.CfgXmlAccessService.LOADED_CONFIG_KEY;
/**
* Builder for standard {@link ServiceRegistry} instances.
*
@ -39,24 +41,27 @@ import org.hibernate.service.spi.ServiceContributor;
*/
public class StandardServiceRegistryBuilder {
/**
* Intended only for use from {@link org.hibernate.jpa.boot.internal.EntityManagerFactoryBuilderImpl}.
* Creates a {@code StandardServiceRegistryBuilder} specific to the needs
* of bootstrapping JPA.
* <p>
* Intended only for use from
* {@link org.hibernate.jpa.boot.internal.EntityManagerFactoryBuilderImpl}.
* <p>
* In particular, we ignore properties found in {@code cfg.xml} files.
* {@code EntityManagerFactoryBuilderImpl} collects these properties later.
*
* Creates a StandardServiceRegistryBuilder specific to the needs of JPA bootstrapping.
* Specifically we ignore properties found in `cfg.xml` files in terms of adding them to
* the builder immediately. EntityManagerFactoryBuilderImpl handles collecting these
* properties itself.
* @see org.hibernate.jpa.boot.internal.EntityManagerFactoryBuilderImpl
*/
public static StandardServiceRegistryBuilder forJpa(BootstrapServiceRegistry bootstrapServiceRegistry) {
final LoadedConfig loadedConfig = new LoadedConfig( null ) {
@Override
protected void addConfigurationValues(Map<String,Object> configurationValues) {
// here, do nothing
}
};
return new StandardServiceRegistryBuilder(
bootstrapServiceRegistry,
new HashMap<>(),
loadedConfig
new LoadedConfig( null ) {
@Override
protected void addConfigurationValues(Map<String,Object> configurationValues) {
// here, do nothing
}
}
) {
@Override
public StandardServiceRegistryBuilder configure(LoadedConfig loadedConfig) {
@ -68,7 +73,7 @@ public class StandardServiceRegistryBuilder {
}
/**
* The default resource name for a Hibernate configuration xml file.
* The default resource name for a Hibernate configuration XML file.
*/
public static final String DEFAULT_CFG_RESOURCE_NAME = "hibernate.cfg.xml";
@ -99,8 +104,10 @@ public class StandardServiceRegistryBuilder {
}
/**
* Intended for use exclusively from JPA bootstrapping, or extensions of
* this class. Consider this an SPI.
* Intended for use exclusively from JPA bootstrapping, or extensions of this
* class.
*
* Consider this an SPI.
*
* @see #forJpa
*/
@ -118,8 +125,11 @@ public class StandardServiceRegistryBuilder {
/**
* Intended for use exclusively from Quarkus bootstrapping, or extensions of
* this class which need to override the standard ServiceInitiator list.
*
* Consider this an SPI.
* @deprecated Quarkus will switch to use {@link #StandardServiceRegistryBuilder(BootstrapServiceRegistry, Map, ConfigLoader, LoadedConfig, List)}
*
* @deprecated Quarkus will switch to use
* {@link #StandardServiceRegistryBuilder(BootstrapServiceRegistry, Map, ConfigLoader, LoadedConfig, List)}
*/
@Deprecated
protected StandardServiceRegistryBuilder(
@ -137,6 +147,7 @@ public class StandardServiceRegistryBuilder {
/**
* Intended for use exclusively from Quarkus bootstrapping, or extensions of
* this class which need to override the standard ServiceInitiator list.
*
* Consider this an SPI.
*/
protected StandardServiceRegistryBuilder(
@ -184,9 +195,7 @@ public class StandardServiceRegistryBuilder {
* @return List of standard initiators
*/
private static List<StandardServiceInitiator<?>> standardInitiatorList() {
final List<StandardServiceInitiator<?>> initiators = new ArrayList<>( StandardServiceInitiators.LIST.size() );
initiators.addAll( StandardServiceInitiators.LIST );
return initiators;
return new ArrayList<>( StandardServiceInitiators.LIST );
}
public BootstrapServiceRegistry getBootstrapServiceRegistry() {
@ -196,10 +205,11 @@ public class StandardServiceRegistryBuilder {
/**
* Read settings from a {@link java.util.Properties} file by resource name.
* <p>
* Differs from {@link #configure()} and {@link #configure(String)} in that here we expect to read a
* {@link java.util.Properties} file while for {@link #configure} we read the XML variant.
* Differs from {@link #configure()} and {@link #configure(String)} in that
* here we expect to read a {@linkplain java.util.Properties properties} file,
* while for {@link #configure} we read the configuration from XML.
*
* @param resourceName The name by which to perform a resource look up for the properties file.
* @param resourceName The name by which to perform a resource look up for the properties file
*
* @return this, for method chaining
*
@ -214,8 +224,9 @@ public class StandardServiceRegistryBuilder {
/**
* Read settings from a {@link java.util.Properties} file by File reference
* <p>
* Differs from {@link #configure()} and {@link #configure(String)} in that here we expect to read a
* {@link java.util.Properties} file while for {@link #configure} we read the XML variant.
* Differs from {@link #configure()} and {@link #configure(String)} in that
* here we expect to read a {@linkplain java.util.Properties properties} file,
* while for {@link #configure} we read the configuration from XML.
*
* @param file The properties File reference
*
@ -332,51 +343,47 @@ public class StandardServiceRegistryBuilder {
*
* @return this, for method chaining
*/
public <T extends Service> StandardServiceRegistryBuilder addService(final Class<T> serviceRole, final T service) {
public <T extends Service> StandardServiceRegistryBuilder addService(Class<T> serviceRole, T service) {
providedServices.add( new ProvidedService<>( serviceRole, service ) );
return this;
}
/**
* By default, when a ServiceRegistry is no longer referenced by any other
* registries as a parent it will be closed.
* <p/>
* Some applications that explicitly build "shared registries" may want to
* circumvent that behavior.
* By default, when a {@link ServiceRegistry} is no longer referenced by any
* other registries as a parent it will be closed. Some applications that
* explicitly build "shared registries" may need to circumvent that behavior.
* <p/>
* This method indicates that the registry being built should not be
* automatically closed. The caller agrees to take responsibility to
* close it themselves.
* automatically closed. The caller takes responsibility for closing it.
*
* @return this, for method chaining
*/
public StandardServiceRegistryBuilder disableAutoClose() {
this.autoCloseRegistry = false;
autoCloseRegistry = false;
return this;
}
/**
* See the discussion on {@link #disableAutoClose}. This method enables
* the auto-closing.
* Enables {@link #disableAutoClose auto-closing}.
*
* @return this, for method chaining
*/
public StandardServiceRegistryBuilder enableAutoClose() {
this.autoCloseRegistry = true;
autoCloseRegistry = true;
return this;
}
/**
* Build the StandardServiceRegistry.
* Build and resturn the {@link StandardServiceRegistry}.
*
* @return The StandardServiceRegistry.
* @return A newly-instantiated {@link StandardServiceRegistry}
*/
public StandardServiceRegistry build() {
applyServiceContributingIntegrators();
applyServiceContributors();
final Map<String,Object> settingsCopy = new HashMap<>( settings );
settingsCopy.put( org.hibernate.boot.cfgxml.spi.CfgXmlAccessService.LOADED_CONFIG_KEY, aggregatedCfgXml );
settingsCopy.put( LOADED_CONFIG_KEY, aggregatedCfgXml );
ConfigurationHelper.resolvePlaceHolders( settingsCopy );
return new StandardServiceRegistryImpl(
@ -410,13 +417,12 @@ public class StandardServiceRegistryBuilder {
}
/**
* Temporarily exposed since Configuration is still around and much code still uses Configuration. This allows
* code to configure the builder and access that to configure Configuration object (used from HEM atm).
* Obtain the current aggregated settings.
*
* @return The settings map.
*
* @deprecated Temporarily exposed since Configuration is still around and much code still uses Configuration.
* This allows code to configure the builder and access that to configure Configuration object.
* @deprecated Temporarily exposed since
* {@link org.hibernate.cfg.Configuration} is still around and much code
* still uses it. This allows code to configure the builder and access
* that to configure the {@code Configuration} object.
*/
@Deprecated
public Map<String,Object> getSettings() {
@ -424,15 +430,15 @@ public class StandardServiceRegistryBuilder {
}
/**
* Destroy a service registry. Applications should only destroy registries they have explicitly created.
* Destroy a service registry.
* <p>
* Applications should only destroy registries they have explicitly created.
*
* @param serviceRegistry The registry to be closed.
*/
public static void destroy(ServiceRegistry serviceRegistry) {
if ( serviceRegistry == null ) {
return;
if ( serviceRegistry != null ) {
( (StandardServiceRegistryImpl) serviceRegistry ).destroy();
}
( (StandardServiceRegistryImpl) serviceRegistry ).destroy();
}
}

208
hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java
View File

@ -60,27 +60,37 @@ import org.hibernate.type.SerializationException;
import org.hibernate.usertype.UserType;
/**
* Represents one approach for bootstrapping Hibernate. In fact, historically this was
* <b>the</b> way to bootstrap Hibernate.
* <p/>
* The approach here is to define all configuration and mapping sources in one API
* and to then build the {@link SessionFactory} in one-shot. The configuration
* and mapping sources defined here are just held here until the SessionFactory is built. This
* is an important distinction from the legacy behavior of this class, where we would try to
* incrementally build the mappings from sources as they were added. The ramification of this
* change in behavior is that users can add configuration and mapping sources here, but they can
* no longer query the in-flight state of mappings ({@link org.hibernate.mapping.PersistentClass},
* {@link org.hibernate.mapping.Collection}, etc) here.
* <p/>
* Note: Internally this class uses the new bootstrapping approach when asked to build the
* SessionFactory.
* A convenience API making it easier to bootstrap an instance of Hibernate
* using {@link MetadataBuilder} and {@link StandardServiceRegistryBuilder}
* under the covers.
* <p>
* A {@code Configuration} may be used to aggregate:
* <ul>
* <li>{@linkplain #setProperty(String, String) configuration properties}
* from various sources, and
* <li>entity O/R mappings, defined in either {@linkplain #addAnnotatedClass
* annotated classes}, or {@linkplain #addFile XML mapping documents}.
* </ul>
* In addition, there are convenience methods for adding
* {@link #addAttributeConverter attribute converters},
* {@link #registerTypeContributor type contributors}, and
* {@link #addSqlFunction SQL function descriptors}, for setting
* {@link #setImplicitNamingStrategy naming strategies} and
* {@link #setCurrentTenantIdentifierResolver tenant id resolvers},
* and more.
* <p>
* Ultimately, this class simply delegates to {@link MetadataBuilder} and
* {@link StandardServiceRegistryBuilder} to actually do the hard work of
* {@linkplain #buildSessionFactory() building} the {@code SessionFactory}.
* <p>
* Configuration properties are enumerated by {@link AvailableSettings}.
*
* @author Gavin King
* @author Steve Ebersole
*
* @see SessionFactory
* @see AvailableSettings
*/
@SuppressWarnings( {"UnusedDeclaration"})
public class Configuration {
private static final CoreMessageLogger log = CoreLogging.messageLogger( Configuration.class );
@ -234,7 +244,8 @@ public class Configuration {
}
/**
* Use the mappings and properties specified in an application resource named {@code hibernate.cfg.xml}.
* Use the mappings and properties specified in an application resource named
* {@code hibernate.cfg.xml}.
*
* @return this for method chaining
*
@ -247,8 +258,9 @@ public class Configuration {
}
/**
* Use the mappings and properties specified in the given application resource. The format of the resource is
* defined in {@code hibernate-configuration-3.0.dtd}.
* Use the mappings and properties specified in the given application resource.
* <p>
* The format of the resource is defined by {@code hibernate-configuration-3.0.dtd}.
*
* @param resource The resource to use
*
@ -272,8 +284,9 @@ public class Configuration {
}
/**
* Use the mappings and properties specified in the given document. The format of the document is defined in
* {@code hibernate-configuration-3.0.dtd}.
* Use the mappings and properties specified in the given document.
* <p>
* The format of the document is defined by {@code hibernate-configuration-3.0.dtd}.
*
* @param url URL from which you wish to load the configuration
*
@ -288,8 +301,9 @@ public class Configuration {
}
/**
* Use the mappings and properties specified in the given application file. The format of the file is defined in
* {@code hibernate-configuration-3.0.dtd}.
* Use the mappings and properties specified in the given application file.
* <p>
* The format of the file is defined by {@code hibernate-configuration-3.0.dtd}.
*
* @param configFile File from which you wish to load the configuration
*
@ -311,8 +325,8 @@ public class Configuration {
}
/**
* Allows registration of a type into the type registry. The phrase 'override' in the method name simply
* reminds that registration *potentially* replaces a previously registered type .
* Register a {@linkplain BasicType type} into the type registry,
* potentially replacing a previously registered type.
*
* @param type The type to register.
*/
@ -349,11 +363,13 @@ public class Configuration {
return this;
}
/**
* Read mappings from a particular XML file
* Read mappings from a particular XML file.
*
* @param xmlFile a path to a file
*
* @return this (for method chaining purposes)
* @throws MappingException Indicates inability to locate the specified mapping file.
*
* @throws MappingException Indicates inability to locate the specified mapping file
*/
public Configuration addFile(File xmlFile) throws MappingException {
metadataSources.addFile( xmlFile );
@ -361,7 +377,8 @@ public class Configuration {
}
/**
* @return An object capable of parsing XML mapping files that can then be passed to {@link #addXmlMapping(Binding)}.
* An object capable of parsing XML mapping files that can then be passed
* to {@link #addXmlMapping(Binding)}.
*/
public XmlMappingBinderAccess getXmlMappingBinderAccess() {
return metadataSources.getXmlMappingBinderAccess();
@ -371,6 +388,7 @@ public class Configuration {
* Read mappings that were parsed using {@link #getXmlMappingBinderAccess()}.
*
* @param binding the parsed mapping
*
* @return this (for method chaining purposes)
*/
public Configuration addXmlMapping(Binding<?> binding) {
@ -379,20 +397,23 @@ public class Configuration {
}
/**
* Add a cached mapping file. A cached file is a serialized representation
* of the DOM structure of a particular mapping. It is saved from a previous
* call as a file with the name {@code xmlFile + ".bin"} where xmlFile is
* the name of the original mapping file.
* Add a cacheable mapping file.
* <p>
* A cached file is a serialized representation of the DOM structure of a
* particular mapping. It is saved from a previous call as a file with the
* name {@code xmlFile + ".bin"} where {@code xmlFile} is the name of the
* original mapping file.
* </p>
* If a cached {@code xmlFile + ".bin"} exists and is newer than
* {@code xmlFile} the {@code ".bin"} file will be read directly. Otherwise
* xmlFile is read and then serialized to {@code xmlFile + ".bin"} for use
* the next time.
* If a cached {@code xmlFile + ".bin"} exists and is newer than {@code xmlFile},
* the {@code ".bin"} file will be read directly. Otherwise, {@code xmlFile} is
* read and then serialized to {@code xmlFile + ".bin"} for use the next time.
*
* @param xmlFile The cacheable mapping file to be added.
*
* @return this (for method chaining purposes)
* @throws MappingException Indicates problems reading the cached file or processing
* the non-cached file.
*
* @throws MappingException Indicates problems reading the cached file or
* processing the non-cached file.
*/
public Configuration addCacheableFile(File xmlFile) throws MappingException {
metadataSources.addCacheableFile( xmlFile );
@ -402,8 +423,9 @@ public class Configuration {
/**
* <b>INTENDED FOR TESTSUITE USE ONLY!</b>
* <p/>
* Much like {@link #addCacheableFile(File)} except that here we will fail immediately if
* the cache version cannot be found or used for whatever reason
* Much like {@link #addCacheableFile(File)} except that here we will fail
* immediately if the cache version cannot be found or used for whatever
* reason.
*
* @param xmlFile The xml file, not the bin!
*
@ -419,11 +441,14 @@ public class Configuration {
/**
* Add a cacheable mapping file.
*
* @param xmlFile The name of the file to be added. This must be in a form
* useable to simply construct a {@link File} instance.
* @param xmlFile The name of the file to be added, in a form usable to
* simply construct a {@link File} instance
*
* @return this (for method chaining purposes)
* @throws MappingException Indicates problems reading the cached file or processing
* the non-cached file.
*
* @throws MappingException Indicates problems reading the cached file or
* processing the non-cached file
*
* @see #addCacheableFile(File)
*/
public Configuration addCacheableFile(String xmlFile) throws MappingException {
@ -432,7 +457,7 @@ public class Configuration {
}
/**
* Read mappings from a {@code URL}
* Read mappings from a {@code URL}.
*
* @param url The url for the mapping document to be read.
* @return this (for method chaining purposes)
@ -458,8 +483,9 @@ public class Configuration {
}
/**
* Read mappings as a application resourceName (i.e. classpath lookup)
* trying different class loaders.
* Read mappings as an application resource name, that is, using a
* {@linkplain ClassLoader#getResource(String) classpath lookup}, trying
* different class loaders in turn.
*
* @param resourceName The resource name
* @return this (for method chaining purposes)
@ -474,7 +500,8 @@ public class Configuration {
/**
* Read a mapping as an application resource using the convention that a class
* named {@code foo.bar.Foo} is mapped by a file {@code foo/bar/Foo.hbm.xml}
* which can be resolved as a classpath resource.
* which can be resolved as a {@linkplain ClassLoader#getResource(String)
* classpath resource}.
*
* @param persistentClass The mapped class
* @return this (for method chaining purposes)
@ -513,7 +540,7 @@ public class Configuration {
}
/**
* Read all mappings from a jar file
* Read all mappings from a {@code .jar} file.
* <p/>
* Assumes that any file named {@code *.hbm.xml} is a mapping document.
*
@ -555,10 +582,9 @@ public class Configuration {
}
/**
* Set the current {@link Interceptor}
* Set the current {@link Interceptor}.
*
* @param interceptor The {@link Interceptor} to use for the {@linkplain #buildSessionFactory built}
* {@link SessionFactory}.
* @param interceptor The {@link Interceptor} to use
*
* @return this for method chaining
*/
@ -568,8 +594,8 @@ public class Configuration {
}
/**
* Retrieve the user-supplied delegate to handle non-existent entity
* scenarios. May be null.
* Retrieve the user-supplied {@link EntityNotFoundDelegate}, or
* {@code null} if no delegate has been specified.
*
* @return The user-supplied delegate
*/
@ -578,9 +604,9 @@ public class Configuration {
}
/**
* Specify a user-supplied delegate to be used to handle scenarios where an entity could not be
* located by specified id. This is mainly intended for EJB3 implementations to be able to
* control how proxy initialization errors should be handled...
* Specify a user-supplied {@link EntityNotFoundDelegate} to be
* used to handle scenarios where an entity could not be located
* by specified id.
*
* @param entityNotFoundDelegate The delegate to use
*/
@ -605,19 +631,21 @@ public class Configuration {
}
/**
* Create a {@link SessionFactory} using the properties and mappings in this configuration. The
* SessionFactory will be immutable, so changes made to this Configuration after building the
* SessionFactory will not affect it.
* Create a {@link SessionFactory} using the properties and mappings
* in this configuration. The {@code SessionFactory} will be immutable,
* so changes made to this {@code Configuration} after building the
* factory will not affect it.
*
* @param serviceRegistry The registry of services to be used in creating this session factory.
*
* @return The built {@link SessionFactory}
* @return The newly-built {@link SessionFactory}
*
* @throws HibernateException usually indicates an invalid configuration or invalid mapping information
*/
public SessionFactory buildSessionFactory(ServiceRegistry serviceRegistry) throws HibernateException {
log.debug( "Building session factory using provided StandardServiceRegistry" );
final MetadataBuilder metadataBuilder = metadataSources.getMetadataBuilder( (StandardServiceRegistry) serviceRegistry );
final MetadataBuilder metadataBuilder =
metadataSources.getMetadataBuilder( (StandardServiceRegistry) serviceRegistry );
if ( implicitNamingStrategy != null ) {
metadataBuilder.applyImplicitNamingStrategy( implicitNamingStrategy );
@ -687,11 +715,12 @@ public class Configuration {
/**
* Create a {@link SessionFactory} using the properties and mappings in this configuration. The
* {@link SessionFactory} will be immutable, so changes made to {@code this} {@link Configuration} after
* building the {@link SessionFactory} will not affect it.
* Create a {@link SessionFactory} using the properties and mappings
* in this configuration. The {@link SessionFactory} will be immutable,
* so changes made to this {@link Configuration} after building the
* factory will not affect it.
*
* @return The build {@link SessionFactory}
* @return The newly-built {@link SessionFactory}
*
* @throws HibernateException usually indicates an invalid configuration or invalid mapping information
*/
@ -708,8 +737,6 @@ public class Configuration {
}
}
public Map<String,SqmFunctionDescriptor> getSqlFunctions() {
return customFunctionDescriptors;
}
@ -729,44 +756,46 @@ public class Configuration {
}
/**
* Adds the AttributeConverter Class to this Configuration.
* Adds an {@link AttributeConverter} to this configuration.
*
* @param attributeConverterClass The AttributeConverter class.
* @param autoApply Should the AttributeConverter be auto applied to property types as specified
* by its "entity attribute" parameterized type?
* @param attributeConverterClass The {@code AttributeConverter} class.
* @param autoApply Should the AttributeConverter be auto applied to
* property types as specified by its "entity attribute"
* parameterized type?
*/
public void addAttributeConverter(Class<? extends AttributeConverter> attributeConverterClass, boolean autoApply) {
addAttributeConverter( new ClassBasedConverterDescriptor( attributeConverterClass, autoApply, classmateContext ) );
}
/**
* Adds the AttributeConverter Class to this Configuration.
* Adds an {@link AttributeConverter} to this configuration.
*
* @param attributeConverterClass The AttributeConverter class.
* @param attributeConverterClass The {@code AttributeConverter} class.
*/
public void addAttributeConverter(Class<? extends AttributeConverter<?,?>> attributeConverterClass) {
addAttributeConverter( new ClassBasedConverterDescriptor( attributeConverterClass, classmateContext ) );
}
/**
* Adds the AttributeConverter instance to this Configuration. This form is mainly intended for developers
* to programmatically add their own AttributeConverter instance. HEM, instead, uses the
* {@link #addAttributeConverter(Class, boolean)} form
* Adds an {@link AttributeConverter} instance to this configuration.
* This form is mainly intended for developers to programmatically add
* their own {@code AttributeConverter} instance.
*
* @param attributeConverter The AttributeConverter instance.
* @param attributeConverter The {@code AttributeConverter} instance.
*/
public void addAttributeConverter(AttributeConverter<?,?> attributeConverter) {
addAttributeConverter( new InstanceBasedConverterDescriptor( attributeConverter, classmateContext ) );
}
/**
* Adds the AttributeConverter instance to this Configuration. This form is mainly intended for developers
* to programmatically add their own AttributeConverter instance. HEM, instead, uses the
* {@link #addAttributeConverter(Class, boolean)} form
* Adds an {@link AttributeConverter} instance to this configuration.
* This form is mainly intended for developers to programmatically add
* their own {@code AttributeConverter} instance.
*
* @param attributeConverter The AttributeConverter instance.
* @param autoApply Should the AttributeConverter be auto applied to property types as specified
* by its "entity attribute" parameterized type?
* @param attributeConverter The {@code AttributeConverter} instance.
* @param autoApply Should the {@code AttributeConverter} be auto applied
* to property types as specified by its "entity attribute"
* parameterized type?
*/
public void addAttributeConverter(AttributeConverter<?,?> attributeConverter, boolean autoApply) {
addAttributeConverter( new InstanceBasedConverterDescriptor( attributeConverter, autoApply, classmateContext ) );
@ -780,10 +809,10 @@ public class Configuration {
}
/**
* Sets the SharedCacheMode to use.
*
* Note that at the moment, only {@link jakarta.persistence.SharedCacheMode#ALL} has
* any effect in terms of {@code hbm.xml} binding.
* Sets the {@link SharedCacheMode} to use.
* <p>
* Note that currently only {@link jakarta.persistence.SharedCacheMode#ALL}
* has any effect in terms of {@code hbm.xml} binding.
*
* @param sharedCacheMode The SharedCacheMode to use
*/
@ -819,8 +848,9 @@ public class Configuration {
}
/**
* Adds the incoming properties to the internal properties structure, as long as the internal structure does not
* already contain an entry for the given key.
* Adds the incoming properties to the internal properties structure, as
* long as the internal structure does not already contain an entry for
* the given key.
*
* @param properties The properties to merge
*