diff --git a/hibernate-core/src/main/java/org/hibernate/boot/Metadata.java b/hibernate-core/src/main/java/org/hibernate/boot/Metadata.java index bf4efb38d4..337b9396b0 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/Metadata.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/Metadata.java @@ -30,9 +30,12 @@ import org.hibernate.query.sqm.function.SqmFunctionDescriptor; /** * Represents the ORM model as determined from all provided mapping sources. + * An instance may be obtained by calling {@link MetadataSources#buildMetadata()}. * - * NOTE : for the time being this is essentially a copy of the legacy Mappings contract, split between - * reading the mapping information exposed here and collecting it via InFlightMetadataCollector + * @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 * diff --git a/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java b/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java index bc97ddd37e..8f60dd1ab5 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java @@ -42,9 +42,14 @@ 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. *

- * A client must register sources and then call {@link #buildMetadata()}, + * 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()}, * or use {@link #getMetadataBuilder()} to customize how the sources are - * processed (naming strategies, etc). + * processed (by registering naming strategies, etc). + *

+ * As an alternative to working directly with {@code MetadataSources}, and + * {@link Metadata}, a program may use {@link org.hibernate.cfg.Configuration}. * * @author Steve Ebersole * @@ -66,12 +71,15 @@ public class MetadataSources implements Serializable { private Map> extraQueryImports; + /** + * Create a new instance, using a default {@link BootstrapServiceRegistry}. + */ public MetadataSources() { this( new BootstrapServiceRegistryBuilder().build() ); } /** - * Create a metadata sources using the specified service registry. + * Create a new instance using the given {@link ServiceRegistry}. * * @param serviceRegistry The service registry to use. */ @@ -103,7 +111,7 @@ public class MetadataSources implements Serializable { protected static boolean isExpectedServiceRegistryType(ServiceRegistry serviceRegistry) { return serviceRegistry instanceof BootstrapServiceRegistry - || serviceRegistry instanceof StandardServiceRegistry; + || serviceRegistry instanceof StandardServiceRegistry; } public XmlMappingBinderAccess getXmlMappingBinderAccess() { @@ -226,7 +234,7 @@ public class MetadataSources implements Serializable { } /** - * Var-arg form of {@link #addAnnotatedClass} + * Vararg form of {@link #addAnnotatedClass(Class)}. */ public MetadataSources addAnnotatedClasses(Class... annotatedClasses) { if ( annotatedClasses != null && annotatedClasses.length > 0 ) { @@ -257,7 +265,7 @@ public class MetadataSources implements Serializable { } /** - * Var-arg form of {@link #addAnnotatedClassName} + * Vararg form of {@link #addAnnotatedClassName(String)}. */ public MetadataSources addAnnotatedClassNames(String... annotatedClassNames) { if ( annotatedClassNames != null && annotatedClassNames.length > 0 ) { @@ -566,9 +574,10 @@ public class MetadataSources implements Serializable { } /** - * Read all mappings from a jar file. + * Read all {@code .hbm.xml} mappings from a jar file. *

* 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 * @@ -591,9 +600,10 @@ public class MetadataSources implements Serializable { } /** - * Read all mapping documents from a directory tree. + * Read all {@code .hbm.xml} mapping documents from a directory tree. *

* Assumes that any file named {@code *.hbm.xml} is a mapping document. + * This method does not support {@code orm.xml} files! * * @param dir The directory * diff --git a/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistry.java b/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistry.java index 4fa82dec7f..3f2eacb23d 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistry.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistry.java @@ -9,9 +9,14 @@ package org.hibernate.boot.registry; import org.hibernate.service.ServiceRegistry; /** - * Provides the most basic services needed. Class loading, etc. - * - * Specialized mainly for type safety. + * Provides the most basic services such as class loading. Other + * configuration-time objects such as {@link org.hibernate.boot.MetadataSources}, + * {@link StandardServiceRegistryBuilder}, and {@link org.hibernate.cfg.Configuration} + * all depend on an instance of {@code BootstrapServiceRegistry}. + *

+ * An instance may be obtained using {@link BootstrapServiceRegistryBuilder#build()}. + *

+ * Specialized from {@link ServiceRegistry} mainly for type safety. * * @see BootstrapServiceRegistryBuilder * diff --git a/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistryBuilder.java b/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistryBuilder.java index c77cb2682c..e2fee7be9a 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistryBuilder.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistryBuilder.java @@ -24,10 +24,17 @@ import org.hibernate.integrator.spi.Integrator; import org.hibernate.service.ServiceRegistry; /** - * Builder for {@link BootstrapServiceRegistry} instances. Provides registry for services needed for - * most operations. This includes {@link Integrator} handling and ClassLoader handling. - * - * Additionally responsible for building and managing the {@link org.hibernate.boot.registry.selector.spi.StrategySelector} + * Builder for {@link BootstrapServiceRegistry} instances. + *

+ * An instance of this class may be obtained by instantiations, simply by + * calling {@code new BootstrapServiceRegistryBuilder()}. Then a new + * {@code BootstrapServiceRegistry} may be obtained by calling {@link #build()}. + * It should be later destroyed by calling {@link #destroy(ServiceRegistry)}. + *

+ * Provides a registry of services needed for most operations. + * Manages a {@link ClassLoaderService}, a set of {@link Integrator}s, and a + * {@link StrategySelectorBuilder} responsible for creation and management + * of {@link org.hibernate.boot.registry.selector.spi.StrategySelector}s. * * @author Steve Ebersole * @author Brett Meyer @@ -39,7 +46,7 @@ public class BootstrapServiceRegistryBuilder { private List providedClassLoaders; private ClassLoaderService providedClassLoaderService; - private StrategySelectorBuilder strategySelectorBuilder = new StrategySelectorBuilder(); + private final StrategySelectorBuilder strategySelectorBuilder = new StrategySelectorBuilder(); private TcclLookupPrecedence tcclLookupPrecedence = TcclLookupPrecedence.AFTER; private boolean autoCloseRegistry = true; @@ -105,7 +112,6 @@ public class BootstrapServiceRegistryBuilder { * * @see org.hibernate.boot.registry.selector.spi.StrategySelector#registerStrategyImplementor(Class, String, Class) */ - @SuppressWarnings( {"UnusedDeclaration"}) public BootstrapServiceRegistryBuilder applyStrategySelector(Class strategy, String name, Class implementation) { this.strategySelectorBuilder.addExplicitStrategyRegistration( strategy, implementation, name ); return this; @@ -120,9 +126,8 @@ public class BootstrapServiceRegistryBuilder { * * @see org.hibernate.boot.registry.selector.spi.StrategySelector#registerStrategyImplementor(Class, String, Class) */ - @SuppressWarnings( {"UnusedDeclaration"}) public BootstrapServiceRegistryBuilder applyStrategySelectors(StrategyRegistrationProvider strategyRegistrationProvider) { - for ( StrategyRegistration strategyRegistration : strategyRegistrationProvider.getStrategyRegistrations() ) { + for ( StrategyRegistration strategyRegistration : strategyRegistrationProvider.getStrategyRegistrations() ) { this.strategySelectorBuilder.addExplicitStrategyRegistration( strategyRegistration ); } return this; diff --git a/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistry.java b/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistry.java index 8574fe03f1..89616e5483 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistry.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistry.java @@ -10,6 +10,8 @@ import org.hibernate.service.ServiceRegistry; /** * Specialization of the {@link ServiceRegistry} contract mainly for type safety. + *

+ * An instance may be obtained using {@link StandardServiceRegistryBuilder#build()}. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistryBuilder.java b/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistryBuilder.java index 427c7df2bc..bb2baf9b9a 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistryBuilder.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistryBuilder.java @@ -377,7 +377,7 @@ public class StandardServiceRegistryBuilder { } /** - * Build and resturn the {@link StandardServiceRegistry}. + * Build and return the {@link StandardServiceRegistry}. * * @return A newly-instantiated {@link StandardServiceRegistry} */ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorBuilder.java b/hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorBuilder.java index 0d132d7083..6f135357bf 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorBuilder.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorBuilder.java @@ -41,14 +41,14 @@ import org.hibernate.type.JsonBJsonFormatMapper; import org.jboss.logging.Logger; /** - * Builder for StrategySelector instances. + * Builder for {@link StrategySelector} instances. * * @author Steve Ebersole */ public class StrategySelectorBuilder { private static final Logger log = Logger.getLogger( StrategySelectorBuilder.class ); - private final List explicitStrategyRegistrations = new ArrayList<>(); + private final List> explicitStrategyRegistrations = new ArrayList<>(); /** * Adds an explicit (as opposed to discovered) strategy registration. @@ -59,7 +59,6 @@ public class StrategySelectorBuilder { * @param The type of the strategy. Used to make sure that the strategy and implementation are type * compatible. */ - @SuppressWarnings("unchecked") public void addExplicitStrategyRegistration(Class strategy, Class implementation, String name) { addExplicitStrategyRegistration( new SimpleStrategyRegistrationImpl<>( strategy, implementation, name ) ); } @@ -114,20 +113,19 @@ public class StrategySelectorBuilder { // apply auto-discovered registrations for ( StrategyRegistrationProvider provider : classLoaderService.loadJavaServices( StrategyRegistrationProvider.class ) ) { - for ( StrategyRegistration discoveredStrategyRegistration : provider.getStrategyRegistrations() ) { + for ( StrategyRegistration discoveredStrategyRegistration : provider.getStrategyRegistrations() ) { applyFromStrategyRegistration( strategySelector, discoveredStrategyRegistration ); } } // apply customizations - for ( StrategyRegistration explicitStrategyRegistration : explicitStrategyRegistrations ) { + for ( StrategyRegistration explicitStrategyRegistration : explicitStrategyRegistrations ) { applyFromStrategyRegistration( strategySelector, explicitStrategyRegistration ); } return strategySelector; } - @SuppressWarnings("unchecked") private void applyFromStrategyRegistration(StrategySelectorImpl strategySelector, StrategyRegistration strategyRegistration) { for ( String name : strategyRegistration.getSelectorNames() ) { strategySelector.registerStrategyImplementor( diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java b/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java index eb57e0a626..681edbf807 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java +++ b/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java @@ -64,6 +64,9 @@ import org.hibernate.usertype.UserType; * using {@link MetadataBuilder} and {@link StandardServiceRegistryBuilder} * under the covers. *

+ * An instance of {@code Configuration} may be obtained simply by + * instantiation, using {@link #Configuration() new Configuration()}. + *

* A {@code Configuration} may be used to aggregate: *

* 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}, + * {@link #registerTypeContributor type contributors}, + * {@link #addSqlFunction SQL function descriptors}, and + * {@link #addAuxiliaryDatabaseObject auxiliary database objects}, for + * setting {@link #setImplicitNamingStrategy naming strategies} and a + * {@link #setCurrentTenantIdentifierResolver tenant id resolver}, * and more. *

+ * Finally, an instance of {@link SessionFactoryBuilder} is obtained by + * calling {@link #buildSessionFactory()}. + *

* Ultimately, this class simply delegates to {@link MetadataBuilder} and * {@link StandardServiceRegistryBuilder} to actually do the hard work of * {@linkplain #buildSessionFactory() building} the {@code SessionFactory}. @@ -125,10 +132,20 @@ public class Configuration { private Properties properties; private SharedCacheMode sharedCacheMode; + /** + * Create a new instance, using a default {@link BootstrapServiceRegistry} + * and a newly instantiated {@link MetadataSources}. + *

+ * This is the usual method of obtaining a {@code Configuration}. + */ public Configuration() { this( new BootstrapServiceRegistryBuilder().build() ); } + /** + * Create a new instance, using the given {@link BootstrapServiceRegistry} + * and a newly instantiated {@link MetadataSources}. + */ public Configuration(BootstrapServiceRegistry serviceRegistry) { this.bootstrapServiceRegistry = serviceRegistry; this.metadataSources = new MetadataSources( serviceRegistry ); @@ -136,6 +153,10 @@ public class Configuration { reset(); } + /** + * Create a new instance, using the given {@link MetadataSources}, and a + * {@link BootstrapServiceRegistry} obtained from the {@link MetadataSources}. + */ public Configuration(MetadataSources metadataSources) { this.bootstrapServiceRegistry = getBootstrapRegistry( metadataSources.getServiceRegistry() ); this.metadataSources = metadataSources; @@ -540,9 +561,10 @@ public class Configuration { } /** - * Read all mappings from a {@code .jar} file. + * Read all {@code .hbm.xml} mappings from a {@code .jar} file. *

* 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 * @return this (for method chaining purposes) @@ -555,9 +577,10 @@ public class Configuration { } /** - * Read all mapping documents from a directory tree. + * Read all {@code .hbm.xml} mapping documents from a directory tree. *

* Assumes that any file named {@code *.hbm.xml} is a mapping document. + * This method does not support {@code orm.xml} files! * * @param dir The directory * @return this (for method chaining purposes) diff --git a/hibernate-core/src/main/java/org/hibernate/service/ServiceRegistry.java b/hibernate-core/src/main/java/org/hibernate/service/ServiceRegistry.java index 80c72bed3a..b7a4381ec1 100644 --- a/hibernate-core/src/main/java/org/hibernate/service/ServiceRegistry.java +++ b/hibernate-core/src/main/java/org/hibernate/service/ServiceRegistry.java @@ -7,7 +7,22 @@ package org.hibernate.service; /** - * A registry of {@linkplain Service services}. + * A registry of {@linkplain Service services}. This interface abstracts + * the operations of: + *

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