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

explain how to get things in the javadoc

This commit is contained in:
Gavin King 2022-01-28 23:32:34 +01:00
parent f388b2fb2b
commit 9276ce4421
9 changed files with 96 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
hibernate-core/src/main/java/org/hibernate/boot/Metadata.java
View File

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

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

@ -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.
* <p>
* 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).
* <p>
* 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<String,Class<?>> 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.
*/
@ -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.
* <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
*
@ -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.
* <p/>
* 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
*

11
hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistry.java
View File

@ -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}.
* <p>
* An instance may be obtained using {@link BootstrapServiceRegistryBuilder#build()}.
* <p>
* Specialized from {@link ServiceRegistry} mainly for type safety.
*
* @see BootstrapServiceRegistryBuilder
*

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

@ -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.
* <p>
* 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)}.
* <p>
* 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<ClassLoader> 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 <T> BootstrapServiceRegistryBuilder applyStrategySelector(Class<T> strategy, String name, Class<? extends T> 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;

2
hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistry.java
View File

@ -10,6 +10,8 @@ import org.hibernate.service.ServiceRegistry;
/**
* Specialization of the {@link ServiceRegistry} contract mainly for type safety.
* <p>
* An instance may be obtained using {@link StandardServiceRegistryBuilder#build()}.
*
* @author Steve Ebersole
*/

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

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

10
hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorBuilder.java
View File

@ -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<StrategyRegistration> explicitStrategyRegistrations = new ArrayList<>();
private final List<StrategyRegistration<?>> explicitStrategyRegistrations = new ArrayList<>();
/**
* Adds an explicit (as opposed to discovered) strategy registration.
@ -59,7 +59,6 @@ public class StrategySelectorBuilder {
* @param <T> The type of the strategy. Used to make sure that the strategy and implementation are type
* compatible.
*/
@SuppressWarnings("unchecked")
public <T> void addExplicitStrategyRegistration(Class<T> strategy, Class<? extends T> 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 <T> void applyFromStrategyRegistration(StrategySelectorImpl strategySelector, StrategyRegistration<T> strategyRegistration) {
for ( String name : strategyRegistration.getSelectorNames() ) {
strategySelector.registerStrategyImplementor(

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

@ -64,6 +64,9 @@ import org.hibernate.usertype.UserType;
* using {@link MetadataBuilder} and {@link StandardServiceRegistryBuilder}
* under the covers.
* <p>
* An instance of {@code Configuration} may be obtained simply by
* instantiation, using {@link #Configuration() new Configuration()}.
* <p>
* A {@code Configuration} may be used to aggregate:
* <ul>
* <li>{@linkplain #setProperty(String, String) configuration properties}
@ -73,12 +76,16 @@ import org.hibernate.usertype.UserType;
* </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},
* {@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.
* <p>
* Finally, an instance of {@link SessionFactoryBuilder} is obtained by
* calling {@link #buildSessionFactory()}.
* <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}.
@ -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}.
* <p>
* 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.
* <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
* @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.
* <p/>
* 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)

17
hibernate-core/src/main/java/org/hibernate/service/ServiceRegistry.java
View File

@ -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:
* <ul>
* <li>{@linkplain org.hibernate.boot.registry.BootstrapServiceRegistry
* bootstrap service registries}, which may be obtained from a
* {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder},
* and
* <li>{@linkplain org.hibernate.boot.registry.StandardServiceRegistry
* standard service registries}, which may be obtained from a
* {@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
*/