From 1fe2509b3b86b54ea9a71d2515e07222c5aab83e Mon Sep 17 00:00:00 2001 From: Gavin Date: Sat, 31 Dec 2022 13:11:22 +0100 Subject: [PATCH] minor edits to the jdoc of o.h.boot.spi package --- .../hibernate/boot/spi/BootstrapContext.java | 31 ++++++++++--------- .../hibernate/boot/spi/ClassLoaderAccess.java | 17 +++++----- .../boot/spi/InFlightMetadataCollector.java | 11 +++++-- .../spi/SessionFactoryBuilderFactory.java | 6 ++-- .../spi/SessionFactoryBuilderImplementor.java | 17 +++++++--- .../EntityManagerFactoryBuilderImpl.java | 3 +- 6 files changed, 50 insertions(+), 35 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/boot/spi/BootstrapContext.java b/hibernate-core/src/main/java/org/hibernate/boot/spi/BootstrapContext.java index 5e7b5ed38d..e06d6d86b7 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/spi/BootstrapContext.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/spi/BootstrapContext.java @@ -41,7 +41,7 @@ import org.jboss.jandex.IndexView; @Incubating public interface BootstrapContext { /** - * The service-registry available to bootstrapping + * The service registry available to bootstrapping */ StandardServiceRegistry getServiceRegistry(); @@ -51,6 +51,8 @@ public interface BootstrapContext { MutableJpaCompliance getJpaCompliance(); /** + * The {@link TypeConfiguration} belonging to this {@code BootstrapContext}. + * * @see TypeConfiguration */ TypeConfiguration getTypeConfiguration(); @@ -81,11 +83,10 @@ public interface BootstrapContext { boolean isJpaBootstrap(); /** - * * Indicates that bootstrap was initiated from JPA bootstrapping. * * @implSpec Internally, {@code false} is the assumed value. - * We only need to call this to mark that as {@code true}. + * We only need to call this to mark it {@code true}. */ void markAsJpaBootstrap(); @@ -94,12 +95,12 @@ public interface BootstrapContext { * {@link jakarta.persistence.spi.PersistenceUnitInfo#getNewTempClassLoader()}, * if any. * - * @return The tempo ClassLoader + * @return The temporary {@code ClassLoader} */ ClassLoader getJpaTempClassLoader(); /** - * Access to class loading capabilities + * Access to class loading capabilities. */ ClassLoaderAccess getClassLoaderAccess(); @@ -119,7 +120,7 @@ public interface BootstrapContext { ArchiveDescriptorFactory getArchiveDescriptorFactory(); /** - * Access to the options to be used for scanning + * Access to the options to be used for scanning. * * @return The scan options */ @@ -135,12 +136,14 @@ public interface BootstrapContext { ScanEnvironment getScanEnvironment(); /** - * Access to the Scanner to be used for scanning. + * Access to the {@link org.hibernate.boot.archive.scan.spi.Scanner} to be used + * for scanning. + *

* Can be: *

* * @return The scanner @@ -160,7 +163,7 @@ public interface BootstrapContext { /** * Access to the Jandex index passed by call to * {@link org.hibernate.boot.MetadataBuilder#applyIndexView(IndexView)}, if any. - *

+ * * @apiNote Jandex is currently not used, see * the roadmap * @@ -170,8 +173,8 @@ public interface BootstrapContext { /** * Access to any SQL functions explicitly registered with the - * {@code MetadataBuilder}. - * This does not include {@code Dialect}-defined functions, etc. + * {@link org.hibernate.boot.MetadataBuilder}. + * This does not include {@code Dialect}-registered functions. *

* Should never return {@code null}. * @@ -181,7 +184,7 @@ public interface BootstrapContext { /** * Access to any {@link AuxiliaryDatabaseObject}s explicitly registered with - * the {@code MetadataBuilder}. + * the {@link org.hibernate.boot.MetadataBuilder}. * This does not include {@link AuxiliaryDatabaseObject}s defined in mappings. *

* Should never return {@code null}. diff --git a/hibernate-core/src/main/java/org/hibernate/boot/spi/ClassLoaderAccess.java b/hibernate-core/src/main/java/org/hibernate/boot/spi/ClassLoaderAccess.java index 21c469dbbd..fe3e2a3709 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/spi/ClassLoaderAccess.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/spi/ClassLoaderAccess.java @@ -9,8 +9,8 @@ package org.hibernate.boot.spi; import java.net.URL; /** - * During the process of building the metamodel, access to the {@link ClassLoader} - * is highly discouraged. However, sometimes it is needed. This contract helps mitigate + * During the process of building the metamodel, access to the {@link ClassLoader} is + * strongly discouraged. However, sometimes it is needed. This contract helps mitigate * access to the {@link ClassLoader} in these cases. * * @author Steve Ebersole @@ -19,20 +19,19 @@ import java.net.URL; */ public interface ClassLoaderAccess { /** - * Obtain a Class reference by name + * Obtain a {@link Class} reference by name * - * @param name The name of the Class to get a reference to. - * - * @return The Class. + * @param name The name of the class + * @return The {@code Class} object with the given name */ Class classForName(String name); /** * Locate a resource by name * - * @param resourceName The name of the resource to resolve. - * - * @return The located resource; may return {@code null} to indicate the resource was not found + * @param resourceName The name of the resource to resolve + * @return The located resource; + * may return {@code null} to indicate the resource was not found */ URL locateResource(String resourceName); } diff --git a/hibernate-core/src/main/java/org/hibernate/boot/spi/InFlightMetadataCollector.java b/hibernate-core/src/main/java/org/hibernate/boot/spi/InFlightMetadataCollector.java index f110798a94..4aa89199f0 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/spi/InFlightMetadataCollector.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/spi/InFlightMetadataCollector.java @@ -188,7 +188,7 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor * * @param typeDefinition The named type definition to add. * - * @throws DuplicateMappingException If a TypeDefinition already exists with that name. + * @throws DuplicateMappingException If a {@link TypeDefinition} already exists with that name. * * @deprecated Use {@link #getTypeDefinitionRegistry()} instead * @@ -197,6 +197,10 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor @Deprecated void addTypeDefinition(TypeDefinition typeDefinition); + /** + * Access to the {@link TypeDefinitionRegistry}, which may be used to add + * type definitions to this metadata repository. + */ TypeDefinitionRegistry getTypeDefinitionRegistry(); /** @@ -204,7 +208,7 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor * * @param definition The filter definition to add. * - * @throws DuplicateMappingException If a FilterDefinition already exists with that name. + * @throws DuplicateMappingException If a {@link FilterDefinition} already exists with that name. */ void addFilterDefinition(FilterDefinition definition); @@ -215,6 +219,9 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor */ void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject auxiliaryDatabaseObject); + /** + * Add a {@link FetchProfile}. + */ void addFetchProfile(FetchProfile profile); // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderFactory.java b/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderFactory.java index 4168cfdb84..a2b9ae5f46 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderFactory.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderFactory.java @@ -10,7 +10,7 @@ import org.hibernate.boot.SessionFactoryBuilder; /** * An extension point for integrators that wish to hook into the process of how a SessionFactory - * is built. Intended as a "discoverable service" ({@link java.util.ServiceLoader}). There can + * is built. Intended as a "discoverable service" ({@link java.util.ServiceLoader}). There can * be at most one implementation discovered that returns a non-null {@link SessionFactoryBuilder}. * * @author Steve Ebersole @@ -20,13 +20,13 @@ public interface SessionFactoryBuilderFactory { * The contract method. Return the {@link SessionFactoryBuilder}. May return {@code null} * * @param metadata The metadata from which we will be building a {@code SessionFactory}. - * @param defaultBuilder The default SessionFactoryBuilder instance. + * @param defaultBuilder The default {@code SessionFactoryBuilder} instance. * If the {@code SessionFactoryBuilder} being built here needs to use * this passed {@code SessionFactoryBuilder} instance, it is the * responsibility of the built {@code SessionFactoryBuilder} impl * to delegate configuration calls to the passed default impl. * - * @return The SessionFactoryBuilder, or {@code null} + * @return The {@code SessionFactoryBuilder}, or {@code null} */ SessionFactoryBuilder getSessionFactoryBuilder(MetadataImplementor metadata, SessionFactoryBuilderImplementor defaultBuilder); } diff --git a/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderImplementor.java b/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderImplementor.java index c4e5bfe6d3..a26f11ca11 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderImplementor.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderImplementor.java @@ -9,22 +9,29 @@ package org.hibernate.boot.spi; import org.hibernate.boot.SessionFactoryBuilder; /** - * Additional contract for {@link SessionFactoryBuilder} mainly intended for implementors - * of {@link SessionFactoryBuilderFactory}. + * Additional SPI contract for {@link SessionFactoryBuilder}, mainly intended for + * implementors of {@link SessionFactoryBuilderFactory}. * * @author Steve Ebersole */ public interface SessionFactoryBuilderImplementor extends SessionFactoryBuilder { + /** + * Called if {@link org.hibernate.cfg.AvailableSettings#ALLOW_JTA_TRANSACTION_ACCESS} + * is not enabled. + */ void disableJtaTransactionAccess(); + /** + * Called if {@link org.hibernate.cfg.AvailableSettings#ALLOW_REFRESH_DETACHED_ENTITY} + * is not enabled. + */ default void disableRefreshDetachedEntity() { } /** - * Build the SessionFactoryOptions that will ultimately be passed to SessionFactoryImpl constructor. - * - * @return The options. + * Build the {@link SessionFactoryOptions} that will ultimately be passed to the + * constructor of {@link org.hibernate.internal.SessionFactoryImpl}. */ SessionFactoryOptions buildSessionFactoryOptions(); } diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java b/hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java index bcc076e07f..ec847998c4 100644 --- a/hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java @@ -89,7 +89,6 @@ import jakarta.persistence.EntityNotFoundException; import jakarta.persistence.PersistenceException; import jakarta.persistence.spi.PersistenceUnitTransactionType; -import static org.hibernate.cfg.AvailableSettings.ALLOW_REFRESH_DETACHED_ENTITY; import static org.hibernate.cfg.AvailableSettings.CFG_XML_FILE; import static org.hibernate.cfg.AvailableSettings.CLASSLOADERS; import static org.hibernate.cfg.AvailableSettings.CLASS_CACHE_PREFIX; @@ -1474,7 +1473,7 @@ public class EntityManagerFactoryBuilderImpl implements EntityManagerFactoryBuil ( ( SessionFactoryBuilderImplementor ) sfBuilder ).disableJtaTransactionAccess(); } - final boolean allowRefreshDetachedEntity = readBooleanConfigurationValue( ALLOW_REFRESH_DETACHED_ENTITY ); + final boolean allowRefreshDetachedEntity = readBooleanConfigurationValue( AvailableSettings.ALLOW_REFRESH_DETACHED_ENTITY ); if ( !allowRefreshDetachedEntity ) { ( (SessionFactoryBuilderImplementor) sfBuilder ).disableRefreshDetachedEntity(); }