properly document TypeContributor and FunctionContributor
This commit is contained in:
Gavin
parent
ce7193696d
commit
a3059fb9d7
|
|
@ -234,7 +234,8 @@ public interface MetadataBuilder {
|
|||
* Again the premise here is JPA portability, bearing in mind that some
|
||||
* JPA provider need these discriminators.
|
||||
* <p>
|
||||
* Its default is defined by the {@value org.hibernate.cfg.AvailableSettings#IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS}
|
||||
* Its default is defined by the
|
||||
* {@value org.hibernate.cfg.AvailableSettings#IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS}
|
||||
* setting if using property-based configuration.
|
||||
*
|
||||
* @param enabled Should we implicitly create discriminator for joined
|
||||
|
|
@ -309,7 +310,8 @@ public interface MetadataBuilder {
|
|||
MetadataBuilder applyBasicType(UserType<?> type, String... keys);
|
||||
|
||||
/**
|
||||
* Apply an explicit TypeContributor (implicit application via ServiceLoader will still happen too)
|
||||
* Apply an explicit {@link TypeContributor}
|
||||
* (implicit application via {@link java.util.ServiceLoader} will still happen too)
|
||||
*
|
||||
* @param typeContributor The contributor to apply
|
||||
*
|
||||
|
|
@ -318,8 +320,8 @@ public interface MetadataBuilder {
|
|||
MetadataBuilder applyTypes(TypeContributor typeContributor);
|
||||
|
||||
/**
|
||||
* Apply a CacheRegionDefinition to be applied to an entity, collection or query while building the
|
||||
* Metadata object.
|
||||
* Apply a {@link CacheRegionDefinition} to be applied to an entity, collection,
|
||||
* or query while building the {@link Metadata} object.
|
||||
*
|
||||
* @param cacheRegionDefinition The cache region definition to apply
|
||||
*
|
||||
|
|
@ -328,26 +330,30 @@ public interface MetadataBuilder {
|
|||
MetadataBuilder applyCacheRegionDefinition(CacheRegionDefinition cacheRegionDefinition);
|
||||
|
||||
/**
|
||||
* Apply a ClassLoader for use while building the Metadata.
|
||||
* Apply a {@link ClassLoader} for use while building the {@link Metadata}.
|
||||
* <p>
|
||||
* Ideally we should avoid accessing ClassLoaders when perform 1st phase of bootstrap. This
|
||||
* is a ClassLoader that can be used in cases when we have to. IN EE managed environments, this
|
||||
* is the ClassLoader mandated by
|
||||
* {@link jakarta.persistence.spi.PersistenceUnitInfo#getNewTempClassLoader()}. This ClassLoader
|
||||
* is thrown away by the container afterwards. The idea being that the Class can still be enhanced
|
||||
* in the application ClassLoader. In other environments, pass a ClassLoader that performs the
|
||||
* same function if desired.
|
||||
* Ideally we should avoid accessing {@code ClassLoader}s when perform 1st phase of bootstrap.
|
||||
* This is a {@code ClassLoader} that can be used in cases where we absolutely must.
|
||||
* <p>
|
||||
* In EE managed environments, this is the {@code ClassLoader} mandated by
|
||||
* {@link jakarta.persistence.spi.PersistenceUnitInfo#getNewTempClassLoader()}.
|
||||
* This {@code ClassLoader} is discarded by the container afterward, the idea being that the
|
||||
* {@link Class} can still be enhanced in the application {@code ClassLoader}.
|
||||
* <p>
|
||||
* In other environments, pass a {@code ClassLoader} that performs the same function, if desired.
|
||||
*
|
||||
* @param tempClassLoader ClassLoader for use during building the Metadata
|
||||
* @param tempClassLoader {@code ClassLoader} for use while building the {@code Metadata}
|
||||
*
|
||||
* @return {@code this}, for method chaining
|
||||
*/
|
||||
MetadataBuilder applyTempClassLoader(ClassLoader tempClassLoader);
|
||||
|
||||
/**
|
||||
* Apply a specific ordering to the processing of sources. Note that unlike most
|
||||
* of the methods on this contract that deal with multiple values internally, this
|
||||
* one *replaces* any already set (its more a setter) instead of adding to.
|
||||
* Apply a specific ordering to the processing of sources.
|
||||
* <p>
|
||||
* Unlike most of the methods of this interface (which deal with multiple
|
||||
* values internally), this one <em>replaces</em> any source processing
|
||||
* order that was already set.
|
||||
* <p>
|
||||
* Its default is defined by the {@value org.hibernate.cfg.AvailableSettings#ARTIFACT_PROCESSING_ORDER}
|
||||
* setting if using property-based configuration.
|
||||
|
|
@ -395,7 +401,8 @@ public interface MetadataBuilder {
|
|||
<O,R> MetadataBuilder applyAttributeConverter(Class<? extends AttributeConverter<O,R>> attributeConverterClass);
|
||||
|
||||
/**
|
||||
* Adds an AttributeConverter by its Class plus a boolean indicating whether to auto apply it.
|
||||
* Adds an {@link AttributeConverter} by {@code Class},
|
||||
* explicitly indicating whether to auto-apply it.
|
||||
*
|
||||
* @param attributeConverterClass The AttributeConverter class.
|
||||
* @param autoApply Should the AttributeConverter be auto applied to property types as specified
|
||||
|
|
@ -415,7 +422,8 @@ public interface MetadataBuilder {
|
|||
<O,R> MetadataBuilder applyAttributeConverter(AttributeConverter<O,R> attributeConverter);
|
||||
|
||||
/**
|
||||
* Adds an AttributeConverter instance, explicitly indicating whether to auto-apply.
|
||||
* Adds an {@link AttributeConverter} instance,
|
||||
* explicitly indicating whether to auto-apply it.
|
||||
*
|
||||
* @param attributeConverter The AttributeConverter instance.
|
||||
* @param autoApply Should the AttributeConverter be auto applied to property types as specified
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ import org.hibernate.cache.spi.access.AccessType;
|
|||
import org.hibernate.internal.util.StringHelper;
|
||||
|
||||
/**
|
||||
* Models the caching options for an entity, natural-id or collection.
|
||||
* Models the caching options for an entity, natural id, or collection.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
* @author Hardy Ferentschik
|
||||
|
|
|
|||
|
|
@ -12,7 +12,11 @@ import org.hibernate.service.ServiceRegistry;
|
|||
import org.hibernate.type.spi.TypeConfiguration;
|
||||
|
||||
/**
|
||||
* Defines the target contributing functions, whether via dialects or {@link FunctionContributor}
|
||||
* Allows custom function descriptors to be contributed to the eventual
|
||||
* {@link SqmFunctionRegistry}, either by a {@link org.hibernate.dialect.Dialect}
|
||||
* or by a {@link FunctionContributor}.
|
||||
*
|
||||
* @see FunctionContributor
|
||||
*
|
||||
* @author Christian Beikov
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -14,12 +14,15 @@
|
|||
|
||||
package org.hibernate.boot.model;
|
||||
|
||||
import org.hibernate.query.sqm.function.SqmFunctionRegistry;
|
||||
|
||||
/**
|
||||
* Contract for contributing functions
|
||||
* On object that contributes custom types and type descriptors, eventually
|
||||
* to a {@link org.hibernate.query.sqm.function.SqmFunctionRegistry}, via an
|
||||
* instance of {@link FunctionContributions}.
|
||||
* <p>
|
||||
* The most common way to integrate a {@code FunctionContributor} is by making
|
||||
* it discoverable via the Java {@link java.util.ServiceLoader} facility.
|
||||
*
|
||||
* @see SqmFunctionRegistry
|
||||
* @see org.hibernate.query.sqm.function.SqmFunctionRegistry
|
||||
*
|
||||
* @author Karel Maesen
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -17,7 +17,11 @@ import org.hibernate.type.spi.TypeConfiguration;
|
|||
import org.hibernate.usertype.UserType;
|
||||
|
||||
/**
|
||||
* Defines the target contributing types, whether via dialects or {@link TypeContributor}
|
||||
* Allows custom types and type descriptors to be contributed to the eventual
|
||||
* {@link TypeConfiguration}, either by a {@link org.hibernate.dialect.Dialect}
|
||||
* or by a {@link TypeContributor}.
|
||||
*
|
||||
* @see TypeContributor
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
@ -25,31 +29,31 @@ public interface TypeContributions {
|
|||
TypeConfiguration getTypeConfiguration();
|
||||
|
||||
/**
|
||||
* Add the JavaType to the {@link TypeConfiguration}'s
|
||||
* {@link JavaTypeRegistry}
|
||||
* Add the given {@link JavaType} to the {@link JavaTypeRegistry}
|
||||
* of the eventual {@link TypeConfiguration}.
|
||||
*/
|
||||
default void contributeJavaType(JavaType<?> descriptor) {
|
||||
getTypeConfiguration().getJavaTypeRegistry().addDescriptor( descriptor );
|
||||
}
|
||||
|
||||
/**
|
||||
* Add the JdbcType to the {@link TypeConfiguration}'s
|
||||
* {@link JdbcTypeRegistry}
|
||||
* Add the given {@link JdbcType} to the {@link JdbcTypeRegistry}
|
||||
* of the eventual {@link TypeConfiguration}.
|
||||
*/
|
||||
default void contributeJdbcType(JdbcType descriptor) {
|
||||
getTypeConfiguration().getJdbcTypeRegistry().addDescriptor( descriptor );
|
||||
}
|
||||
|
||||
/**
|
||||
* Registers a UserType as the implicit (auto-applied) type
|
||||
* for values of type {@link UserType#returnedClass()}
|
||||
* Register a {@link UserType} as the implicit (auto-applied)
|
||||
* type for values of type {@link UserType#returnedClass()}
|
||||
*/
|
||||
default <T> void contributeType(UserType<T> type) {
|
||||
contributeType( type, type.returnedClass().getName() );
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated See user-guide section `2.2.46. TypeContributor` for details - `basic_types.adoc`
|
||||
* @deprecated See discussion of {@code TypeContributor} in User Guide.
|
||||
*/
|
||||
@Deprecated(since = "6.0")
|
||||
default void contributeType(BasicType<?> type) {
|
||||
|
|
|
|||
|
|
@ -9,9 +9,20 @@ package org.hibernate.boot.model;
|
|||
import org.hibernate.service.ServiceRegistry;
|
||||
|
||||
/**
|
||||
* Contract for contributing types.
|
||||
* On object that contributes custom types and type descriptors, eventually
|
||||
* to a {@link org.hibernate.type.spi.TypeConfiguration}, via an instance
|
||||
* of {@link TypeContributions}.
|
||||
* <p>
|
||||
* The most common way to integrate a {@code TypeContributor} is by making
|
||||
* it discoverable via the Java {@link java.util.ServiceLoader} facility.
|
||||
* <p>
|
||||
* Alternatively, a {@code TypeContributor} may be supplied to
|
||||
* {@link org.hibernate.cfg.Configuration#registerTypeContributor(TypeContributor)}
|
||||
* or even {@link org.hibernate.boot.MetadataBuilder#applyTypes(TypeContributor)}.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*
|
||||
* @see org.hibernate.type.spi.TypeConfiguration
|
||||
*/
|
||||
public interface TypeContributor {
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -44,12 +44,13 @@ import org.hibernate.usertype.UserType;
|
|||
import static org.hibernate.mapping.MappingHelper.injectParameters;
|
||||
|
||||
/**
|
||||
* Models the information pertaining to a custom type definition supplied by the user. Used
|
||||
* to delay instantiation of the actual {@link Type} instance.
|
||||
*
|
||||
* Models the information pertaining to a custom type definition supplied by the user.
|
||||
* Used to delay instantiation of the actual {@link Type} instance.
|
||||
* <p>
|
||||
* Generally speaking this information would come from annotations
|
||||
* ({@link org.hibernate.annotations.Type}) or XML mappings. An alternative form of
|
||||
* supplying custom types is programmatically via one of:<ul>
|
||||
* ({@link org.hibernate.annotations.Type}) or XML mappings. An alternative way to
|
||||
* supply custom types is programmatically, via one of:
|
||||
* <ul>
|
||||
* <li>{@link org.hibernate.boot.MetadataBuilder#applyBasicType(BasicType)}</li>
|
||||
* <li>{@link org.hibernate.boot.MetadataBuilder#applyBasicType(UserType, String[])}</li>
|
||||
* <li>{@link org.hibernate.boot.MetadataBuilder#applyTypes(TypeContributor)}</li>
|
||||
|
|
|
|||
|
|
@ -11,6 +11,12 @@
|
|||
* and the mapping of these "domain model parts" to the database. It is
|
||||
* {@linkplain org.hibernate.boot.model.process built incrementally} from
|
||||
* {@linkplain org.hibernate.annotations annotations} and XML-based mappings.
|
||||
* <p>
|
||||
* The interfaces {@link org.hibernate.boot.model.TypeContributor} and
|
||||
* {@link org.hibernate.boot.model.FunctionContributor} allow a program
|
||||
* or library to contribute custom types and type descriptors, and
|
||||
* custom function descriptors, respectively, to Hibernate during the
|
||||
* bootstrap process.
|
||||
*
|
||||
* @implNote Ultimately, as part of the process of creating the
|
||||
* {@link org.hibernate.SessionFactory}, Hibernate
|
||||
|
|
|
|||
|
|
@ -9,8 +9,14 @@ package org.hibernate.boot.registry.selector;
|
|||
/**
|
||||
* Responsible for providing the registrations of one or more strategy selectors.
|
||||
* <p>
|
||||
* Can be registered directly with the {@link org.hibernate.boot.registry.BootstrapServiceRegistry}
|
||||
* or located via discovery.
|
||||
* A {@code StrategyRegistrationProvider} may be made available either by:
|
||||
* <ul>
|
||||
* <li>registering it directly with the
|
||||
* {@link org.hibernate.boot.registry.BootstrapServiceRegistry} by calling
|
||||
* {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder#applyStrategySelectors},
|
||||
* or
|
||||
* <li>by making it discoverable via the Java {@link java.util.ServiceLoader} facility.
|
||||
* </ul>
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -398,6 +398,9 @@ public class Configuration {
|
|||
|
||||
// MetadataSources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
/**
|
||||
* Add a {@link TypeContributor} to this configuration.
|
||||
*/
|
||||
public Configuration registerTypeContributor(TypeContributor typeContributor) {
|
||||
typeContributorRegistrations.add( typeContributor );
|
||||
return this;
|
||||
|
|
|
|||
|
|
@ -15,8 +15,9 @@ import org.hibernate.service.spi.SessionFactoryServiceRegistry;
|
|||
/**
|
||||
* Contract for extensions that integrate with Hibernate.
|
||||
* <p>
|
||||
* An implementation of {@code Integrator} is discoverable via the standard Java
|
||||
* {@link java.util.ServiceLoader} facility.
|
||||
* The best way to make an implementation of {@code Integrator} available to Hibernate
|
||||
* is by making it discoverable via the standard Java {@link java.util.ServiceLoader}
|
||||
* facility.
|
||||
*
|
||||
* @implNote {@link #integrate(Metadata, BootstrapContext, SessionFactoryImplementor)}
|
||||
* is called during the process of {@linkplain SessionFactoryImplementor
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ import org.hibernate.integrator.spi.Integrator;
|
|||
/**
|
||||
* An object that provides a list of {@link Integrator}s to the JPA persistence provider.
|
||||
* <p>
|
||||
* In implementation may be registered with the JPA provider using the property
|
||||
* An implementation may be registered with the JPA provider using the property
|
||||
* {@value org.hibernate.jpa.boot.spi.JpaSettings#INTEGRATOR_PROVIDER}.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ import org.hibernate.boot.registry.selector.StrategyRegistrationProvider;
|
|||
/**
|
||||
* An object that provides a list of {@link StrategyRegistrationProvider}s to the JPA persistence provider.
|
||||
* <p>
|
||||
* In implementation may be registered with the JPA provider using the property
|
||||
* An implementation may be registered with the JPA provider using the property
|
||||
* {@value org.hibernate.jpa.boot.spi.JpaSettings#STRATEGY_REGISTRATION_PROVIDERS}.
|
||||
*
|
||||
* @author Brett Meyer
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ import org.hibernate.boot.model.TypeContributor;
|
|||
/**
|
||||
* An object that provides a list of {@link TypeContributor}s to the JPA persistence provider.
|
||||
* <p>
|
||||
* In implementation may be registered with the JPA provider using the property
|
||||
* An implementation may be registered with the JPA provider using the property
|
||||
* {@value org.hibernate.jpa.boot.spi.JpaSettings#TYPE_CONTRIBUTORS}.
|
||||
*
|
||||
* @author Brett Meyer
|
||||
|
|
|
|||
|
|
@ -40,6 +40,11 @@
|
|||
* of {@code BigInteger} to and from {@code String} when writing to and reading from
|
||||
* JDBC statements and result sets.
|
||||
* <p>
|
||||
* An important point is that the set of available {@code JavaType}s and of available
|
||||
* {@code JdbcType}s is not fixed—a {@link org.hibernate.type.spi.TypeConfiguration}
|
||||
* is {@linkplain org.hibernate.boot.model.TypeContributions customizable during the
|
||||
* bootstrap process}.
|
||||
* <p>
|
||||
* This approach provides quite some flexibility in allowing a given Java type to
|
||||
* map to a range of JDBC types. However, when the built-in conversions don't handle
|
||||
* a particular mapping, a
|
||||
|
|
|
|||
|
|
@ -87,10 +87,14 @@ import static org.hibernate.internal.CoreLogging.messageLogger;
|
|||
* <p>
|
||||
* However, a {@code Type} will often want access to the {@code TypeConfiguration}, which can be
|
||||
* achieved by the {@code Type} simply implementing the {@link TypeConfigurationAware} interface.
|
||||
* <p>
|
||||
* A {@code TypeConfiguration} may be configured via {@link org.hibernate.boot.model.TypeContributions}.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*
|
||||
* @since 5.3
|
||||
*
|
||||
* @see org.hibernate.boot.model.TypeContributions
|
||||
*/
|
||||
@Incubating
|
||||
public class TypeConfiguration implements SessionFactoryObserver, Serializable {
|
||||
|
|
|
|||
Loading…
Reference in New Issue