HHH-16257 - Add `@JavaServiceLoadable` to document Services or strategies that are loadable as Java services

hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributor.java

@@ -14,6 +14,8 @@
 
 package org.hibernate.boot.model;
 
+import org.hibernate.service.JavaServiceLoadable;
+
 /**
  * On object that contributes custom HQL functions, eventually to a
  * {@link org.hibernate.query.sqm.function.SqmFunctionRegistry}, via an
@@ -33,6 +35,7 @@ package org.hibernate.boot.model;
  *
  * @author Karel Maesen
  */
+@JavaServiceLoadable
 public interface FunctionContributor {
 
 	/**

hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributor.java

@@ -6,6 +6,7 @@
  */
 package org.hibernate.boot.model;
 
+import org.hibernate.service.JavaServiceLoadable;
 import org.hibernate.service.ServiceRegistry;
 
 /**
@@ -31,6 +32,7 @@ import org.hibernate.service.ServiceRegistry;
  *
  * @see org.hibernate.type.spi.TypeConfiguration
  */
+@JavaServiceLoadable
 public interface TypeContributor {
 	/**
 	 * Contribute types

hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/spi/ClassLoaderService.java

@@ -96,22 +96,18 @@ public interface ClassLoaderService extends ResourceLocator, ResourceStreamLocat
 	 * @param <S> The type of the service contract
 	 *     
 	 * @return The ordered set of discovered services.
+	 *
+	 * @see org.hibernate.service.JavaServiceLoadable
 	 */
 	<S> Collection<S> loadJavaServices(Class<S> serviceContract);
 
 	<T> T generateProxy(InvocationHandler handler, Class... interfaces);
 
 	/**
-	 * Loading a Package from the classloader. In case it's not found or an
-	 * internal error (such as @see {@link LinkageError} occurs, we
-	 * return null rather than throwing an exception.
-	 * This is significantly different than loading a Class, as in all
-	 * currently known usages, being unable to load the Package will
-	 * only result in ignoring annotations on it - which is totally
-	 * fine when the object doesn't exist.
-	 * In case of other errors, implementations are expected to log
-	 * a warning but it's still not treated as a fatal error.
-	 * @return the matching Package, or null.
+	 * Loading a Package from the ClassLoader.
+	 *
+	 * @return The Package.  {@code null} if no such Package is found, or if the
+	 * ClassLoader call leads to an exception ({@link LinkageError}, e.g.).
 	 */
 	Package packageForNameOrNull(String packageName);
 

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/StrategyRegistrationProvider.java

@@ -6,6 +6,8 @@
  */
 package org.hibernate.boot.registry.selector;
 
+import org.hibernate.service.JavaServiceLoadable;
+
 /**
  * Responsible for providing the registrations of one or more strategy selectors.
  * <p>
@@ -20,6 +22,7 @@ package org.hibernate.boot.registry.selector;
  *
  * @author Steve Ebersole
  */
+@JavaServiceLoadable
 public interface StrategyRegistrationProvider {
 	/**
 	 * Get all {@link StrategyRegistration}s announced by this provider.

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/spi/DialectSelector.java

@@ -8,10 +8,12 @@ package org.hibernate.boot.registry.selector.spi;
 
 import org.hibernate.boot.registry.selector.internal.LazyServiceResolver;
 import org.hibernate.dialect.Dialect;
+import org.hibernate.service.JavaServiceLoadable;
 import org.hibernate.service.Service;
 
 /**
  * @author Christian Beikov
  */
+@JavaServiceLoadable
 public interface DialectSelector extends Service, LazyServiceResolver<Dialect> {
 }

hibernate-core/src/main/java/org/hibernate/boot/spi/AdditionalMappingContributor.java

@@ -8,6 +8,7 @@ package org.hibernate.boot.spi;
 
 import org.hibernate.Incubating;
 import org.hibernate.boot.ResourceStreamLocator;
+import org.hibernate.service.JavaServiceLoadable;
 
 /**
  * Contract allowing pluggable contributions of additional mapping objects.
@@ -17,6 +18,7 @@ import org.hibernate.boot.ResourceStreamLocator;
  * @author Steve Ebersole
  */
 @Incubating
+@JavaServiceLoadable
 public interface AdditionalMappingContributor {
 	/**
 	 * The name of this contributor.  May be {@code null}.

hibernate-core/src/main/java/org/hibernate/boot/spi/MetadataBuilderFactory.java

@@ -8,6 +8,7 @@ package org.hibernate.boot.spi;
 
 import org.hibernate.boot.Metadata;
 import org.hibernate.boot.MetadataSources;
+import org.hibernate.service.JavaServiceLoadable;
 
 /**
  * An extension point for integrators that wish to hook into the process of how a {@link Metadata} is built. Intended as
@@ -16,6 +17,7 @@ import org.hibernate.boot.MetadataSources;
  *
  * @author Gunnar Morling
  */
+@JavaServiceLoadable
 public interface MetadataBuilderFactory {
 
 	/**

hibernate-core/src/main/java/org/hibernate/boot/spi/MetadataBuilderInitializer.java

@@ -8,6 +8,7 @@ package org.hibernate.boot.spi;
 
 import org.hibernate.boot.MetadataBuilder;
 import org.hibernate.boot.registry.StandardServiceRegistry;
+import org.hibernate.service.JavaServiceLoadable;
 
 /**
  * Contract for contributing to the initialization of {@link MetadataBuilder}.
@@ -20,6 +21,7 @@ import org.hibernate.boot.registry.StandardServiceRegistry;
  *
  * @since 5.0
  */
+@JavaServiceLoadable
 public interface MetadataBuilderInitializer {
 	void contribute(MetadataBuilder metadataBuilder, StandardServiceRegistry serviceRegistry);
 }

hibernate-core/src/main/java/org/hibernate/boot/spi/MetadataSourcesContributor.java

@@ -7,6 +7,7 @@
 package org.hibernate.boot.spi;
 
 import org.hibernate.boot.MetadataSources;
+import org.hibernate.service.JavaServiceLoadable;
 
 /**
  * A bootstrap process hook for contributing sources to {@link MetadataSources}.
@@ -15,6 +16,7 @@ import org.hibernate.boot.MetadataSources;
  *
  * @since 5.0
  */
+@JavaServiceLoadable
 public interface MetadataSourcesContributor {
 	/**
 	 * Perform the process of contributing to the {@link MetadataSources}.

hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryBuilderFactory.java

@@ -7,6 +7,7 @@
 package org.hibernate.boot.spi;
 
 import org.hibernate.boot.SessionFactoryBuilder;
+import org.hibernate.service.JavaServiceLoadable;
 
 /**
  * An extension point for integrators that wish to hook into the process of how a SessionFactory
@@ -15,6 +16,7 @@ import org.hibernate.boot.SessionFactoryBuilder;
  *
  * @author Steve Ebersole
  */
+@JavaServiceLoadable
 public interface SessionFactoryBuilderFactory {
 	/**
 	 * The contract method. Return the {@link SessionFactoryBuilder}. May return {@code null}

hibernate-core/src/main/java/org/hibernate/engine/jdbc/dialect/spi/DialectResolver.java

@@ -7,6 +7,7 @@
 package org.hibernate.engine.jdbc.dialect.spi;
 
 import org.hibernate.dialect.Dialect;
+import org.hibernate.service.JavaServiceLoadable;
 import org.hibernate.service.Service;
 
 /**
@@ -15,6 +16,7 @@ import org.hibernate.service.Service;
  * @author Tomoto Shimizu Washio
  * @author Steve Ebersole
  */
+@JavaServiceLoadable
 public interface DialectResolver extends Service {
 	/**
 	 * Determine the {@link Dialect} to use based on the given information.  Implementations are expected to return

hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/spi/JtaPlatformProvider.java

@@ -6,6 +6,8 @@
  */
 package org.hibernate.engine.transaction.jta.platform.spi;
 
+import org.hibernate.service.JavaServiceLoadable;
+
 /**
  * A {@link java.util.ServiceLoader}-style provider of {@link JtaPlatform}
  * instances. Used when an explicit {@code JtaPlatform} is not provided.
@@ -15,6 +17,7 @@ package org.hibernate.engine.transaction.jta.platform.spi;
  *
  * @author Steve Ebersole
  */
+@JavaServiceLoadable
 public interface JtaPlatformProvider {
 	/**
 	 * Retrieve the JtaPlatform provided by this environment.

hibernate-core/src/main/java/org/hibernate/event/spi/EventEngineContributor.java

@@ -6,6 +6,8 @@
  */
 package org.hibernate.event.spi;
 
+import org.hibernate.service.JavaServiceLoadable;
+
 /**
  * Integration contract for contributing event types and listeners to the Hibernate event system.
  *
@@ -13,6 +15,7 @@ package org.hibernate.event.spi;
  *
  * @author Steve Ebersole
  */
+@JavaServiceLoadable
 public interface EventEngineContributor {
 	/**
 	 * Apply the contributions

hibernate-core/src/main/java/org/hibernate/id/factory/spi/GenerationTypeStrategyRegistration.java

@@ -9,12 +9,14 @@ package org.hibernate.id.factory.spi;
 import java.util.function.BiConsumer;
 import jakarta.persistence.GenerationType;
 
+import org.hibernate.service.JavaServiceLoadable;
 import org.hibernate.service.ServiceRegistry;
 
 /**
  * A {@link java.util.ServiceLoader} contract for registering implementations
  * of {@link GenerationTypeStrategy}.
  */
+@JavaServiceLoadable
 public interface GenerationTypeStrategyRegistration {
 	void registerStrategies(BiConsumer<GenerationType, GenerationTypeStrategy> registry, ServiceRegistry serviceRegistry);
 }

hibernate-core/src/main/java/org/hibernate/integrator/spi/Integrator.java

@@ -10,6 +10,7 @@ import org.hibernate.Incubating;
 import org.hibernate.boot.Metadata;
 import org.hibernate.boot.spi.BootstrapContext;
 import org.hibernate.engine.spi.SessionFactoryImplementor;
+import org.hibernate.service.JavaServiceLoadable;
 import org.hibernate.service.spi.SessionFactoryServiceRegistry;
 
 /**
@@ -29,6 +30,7 @@ import org.hibernate.service.spi.SessionFactoryServiceRegistry;
  * @author Steve Ebersole
  * @since 4.0
  */
+@JavaServiceLoadable
 public interface Integrator {
 
 	/**

hibernate-core/src/main/java/org/hibernate/service/JavaServiceLoadable.java

@@ -0,0 +1,18 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html.
+ */
+package org.hibernate.service;
+
+/**
+ * Marker annotation identifying integration points which Hibernate supports loading as a
+ * {@linkplain java.util.ServiceLoader Java service}.
+ *
+ * @see org.hibernate.boot.registry.classloading.spi.ClassLoaderService#loadJavaServices
+ *
+ * @author Steve Ebersole
+ */
+public @interface JavaServiceLoadable {
+}

hibernate-core/src/main/java/org/hibernate/service/spi/ServiceContributor.java

@@ -7,6 +7,7 @@
 package org.hibernate.service.spi;
 
 import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
+import org.hibernate.service.JavaServiceLoadable;
 
 /**
  * Contract for contributing services.
@@ -16,6 +17,7 @@ import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
  *
  * @author Steve Ebersole
  */
+@JavaServiceLoadable
 public interface ServiceContributor {
 	/**
 	 * Contribute services to the indicated registry builder.

hibernate-core/src/main/java/org/hibernate/service/spi/SessionFactoryServiceContributor.java

@@ -6,9 +6,12 @@
  */
 package org.hibernate.service.spi;
 
+import org.hibernate.service.JavaServiceLoadable;
+
 /**
  * @author Steve Ebersole
  */
+@JavaServiceLoadable
 public interface SessionFactoryServiceContributor {
 	/**
 	 * Contribute services to the indicated registry builder.