HSEARCH-5018 Add hints to failing Jandex discovery error message

marko-bekhta · marko-bekhta · commit 093ea193b41b · 2024-05-01T08:45:28.000+02:00
diff --git a/mapper/orm/src/main/java/org/hibernate/search/mapper/orm/mapping/impl/HibernateOrmMappingInitiator.java b/mapper/orm/src/main/java/org/hibernate/search/mapper/orm/mapping/impl/HibernateOrmMappingInitiator.java
@@ -32,6 +32,7 @@
 import org.hibernate.search.mapper.orm.mapping.HibernateOrmSearchMappingConfigurer;
 import org.hibernate.search.mapper.orm.model.impl.HibernateOrmBasicTypeMetadataProvider;
 import org.hibernate.search.mapper.orm.model.impl.HibernateOrmBootstrapIntrospector;
+import org.hibernate.search.mapper.orm.reporting.impl.HibernateOrmMapperHints;
 import org.hibernate.search.mapper.orm.session.impl.ConfiguredAutomaticIndexingStrategy;
 import org.hibernate.search.mapper.pojo.mapping.building.spi.PojoMapperDelegate;
 import org.hibernate.search.mapper.pojo.mapping.building.spi.PojoTypeMetadataContributor;
@@ -101,7 +102,7 @@ private HibernateOrmMappingInitiator(
 			HibernateOrmBasicTypeMetadataProvider basicTypeMetadataProvider,
 			IndexView jandexIndex, HibernateOrmBootstrapIntrospector introspector,
 			HibernateSearchPreIntegrationService preIntegrationService, boolean multiTenancyEnabled) {
-		super( introspector );
+		super( introspector, HibernateOrmMapperHints.INSTANCE );
 
 		this.basicTypeMetadataProvider = basicTypeMetadataProvider;
 		if ( jandexIndex != null ) {
diff --git a/mapper/orm/src/main/java/org/hibernate/search/mapper/orm/reporting/impl/HibernateOrmMapperHints.java b/mapper/orm/src/main/java/org/hibernate/search/mapper/orm/reporting/impl/HibernateOrmMapperHints.java
@@ -0,0 +1,32 @@
+/*
+ * Hibernate Search, full-text search for your domain model
+ *
+ * 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.search.mapper.orm.reporting.impl;
+
+import org.hibernate.search.mapper.orm.cfg.HibernateOrmMapperSettings;
+import org.hibernate.search.mapper.pojo.reporting.spi.MapperHints;
+import org.hibernate.search.util.common.logging.impl.MessageConstants;
+
+import org.jboss.logging.Messages;
+import org.jboss.logging.annotations.Message;
+import org.jboss.logging.annotations.MessageBundle;
+
+@MessageBundle(projectCode = MessageConstants.PROJECT_CODE)
+public interface HibernateOrmMapperHints extends MapperHints {
+
+	HibernateOrmMapperHints INSTANCE = Messages.getBundle( HibernateOrmMapperHints.class );
+
+	@Message("Prebuild the missing Jandex indexes and make them available to Hibernate Search"
+			+ " or use a combination of configuration properties ("
+			+ " \"" + HibernateOrmMapperSettings.MAPPING_CONFIGURER + "\","
+			+ " \"" + HibernateOrmMapperSettings.MAPPING_DISCOVER_ANNOTATED_TYPES_FROM_ROOT_MAPPING_ANNOTATIONS + "\","
+			+ " \"" + HibernateOrmMapperSettings.MAPPING_BUILD_MISSING_DISCOVERED_JANDEX_INDEXES + "\""
+			+ ") to limit the discovery of annotated types."
+			+ " For specifics, refer to the \"Classpath scanning\""
+			+ " section of the reference documentation.")
+	String cannotReadJandexRootMapping();
+
+}
diff --git a/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/logging/impl/Log.java b/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/logging/impl/Log.java
@@ -743,8 +743,9 @@ SearchException objectProjectionCyclicRecursion(MappingElement objectProjection,
 			String cyclicRecursionIndexFieldPath);
 
 	@Message(id = ID_OFFSET + 119,
-			value = "Exception while retrieving the Jandex index for code source location '%1$s': %2$s")
-	SearchException errorDiscoveringJandexIndex(URL codeSourceLocation, String causeMessage, @Cause Exception cause);
+			value = "Exception while retrieving the Jandex index for code source location '%1$s': %2$s; %3$s")
+	SearchException errorDiscoveringJandexIndex(URL codeSourceLocation, String causeMessage, String hint,
+			@Cause Exception cause);
 
 	@LogMessage(level = Logger.Level.WARN)
 	@Message(id = ID_OFFSET + 120,
diff --git a/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/impl/AnnotationMappingConfigurationContextImpl.java b/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/impl/AnnotationMappingConfigurationContextImpl.java
@@ -30,6 +30,7 @@
 import org.hibernate.search.mapper.pojo.mapping.spi.PojoMappingConfigurationContributor;
 import org.hibernate.search.mapper.pojo.model.spi.PojoBootstrapIntrospector;
 import org.hibernate.search.mapper.pojo.model.spi.PojoRawTypeModel;
+import org.hibernate.search.mapper.pojo.reporting.spi.MapperHints;
 import org.hibernate.search.util.common.jar.impl.JandexUtils;
 import org.hibernate.search.util.common.jar.impl.JarUtils;
 import org.hibernate.search.util.common.jar.spi.JandexBehavior;
@@ -49,6 +50,7 @@ public class AnnotationMappingConfigurationContextImpl
 	private static final Log log = LoggerFactory.make( Log.class, MethodHandles.lookup() );
 
 	private final PojoBootstrapIntrospector introspector;
+	private final MapperHints mapperHints;
 
 	private boolean discoverAnnotatedTypesFromRootMappingAnnotations = false;
 	private boolean discoverJandexIndexesFromAddedTypes = false;
@@ -59,8 +61,10 @@ public class AnnotationMappingConfigurationContextImpl
 	private final Set<Class<?>> explicitAnnotatedTypes = new LinkedHashSet<>();
 	private final List<IndexView> explicitJandexIndexes = new ArrayList<>();
 
-	public AnnotationMappingConfigurationContextImpl(PojoBootstrapIntrospector introspector) {
+	public AnnotationMappingConfigurationContextImpl(PojoBootstrapIntrospector introspector,
+			MapperHints mapperHints) {
 		this.introspector = introspector;
+		this.mapperHints = mapperHints;
 	}
 
 	@Override
@@ -221,7 +225,7 @@ private boolean isJandexBuildingAllowed(Class<?> annotatedType) {
 		}
 	}
 
-	private static Optional<Index> jandexIndexForCodeSourceLocation(URL codeSourceLocation, boolean buildIfMissing) {
+	private Optional<Index> jandexIndexForCodeSourceLocation(URL codeSourceLocation, boolean buildIfMissing) {
 		try {
 			if ( buildIfMissing ) {
 				return Optional.of( JandexUtils.readOrBuildIndex( codeSourceLocation ) );
@@ -231,7 +235,8 @@ private static Optional<Index> jandexIndexForCodeSourceLocation(URL codeSourceLo
 			}
 		}
 		catch (RuntimeException e) {
-			throw log.errorDiscoveringJandexIndex( codeSourceLocation, e.getMessage(), e );
+			throw log.errorDiscoveringJandexIndex( codeSourceLocation, e.getMessage(),
+					mapperHints.cannotReadJandexRootMapping(), e );
 		}
 	}
 
diff --git a/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/spi/AbstractPojoMappingInitiator.java b/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/mapping/spi/AbstractPojoMappingInitiator.java
@@ -36,6 +36,7 @@
 import org.hibernate.search.mapper.pojo.mapping.impl.PojoMappingConfigurationContextImpl;
 import org.hibernate.search.mapper.pojo.model.spi.PojoBootstrapIntrospector;
 import org.hibernate.search.mapper.pojo.model.typepattern.impl.TypePatternMatcherFactory;
+import org.hibernate.search.mapper.pojo.reporting.spi.MapperHints;
 
 public abstract class AbstractPojoMappingInitiator<MPBS extends MappingPartialBuildState>
 		implements MappingInitiator<PojoTypeMetadataContributor, MPBS> {
@@ -58,15 +59,15 @@ public abstract class AbstractPojoMappingInitiator<MPBS extends MappingPartialBu
 	private ContainerExtractorBinder extractorBinder;
 	private BridgeResolver bridgeResolver;
 
-	protected AbstractPojoMappingInitiator(PojoBootstrapIntrospector introspector) {
+	protected AbstractPojoMappingInitiator(PojoBootstrapIntrospector introspector, MapperHints mapperHints) {
 		this.introspector = introspector;
 
 		/*
 		 * Make sure to create and add the annotation mapping even if the user does not call the
 		 * annotationMapping() method to register annotated types explicitly,
 		 * in case annotated type discovery is enabled.
 		 */
-		annotationMappingConfiguration = new AnnotationMappingConfigurationContextImpl( introspector );
+		annotationMappingConfiguration = new AnnotationMappingConfigurationContextImpl( introspector, mapperHints );
 		addConfigurationContributor( annotationMappingConfiguration );
 
 		typePatternMatcherFactory = new TypePatternMatcherFactory( introspector );
diff --git a/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/reporting/spi/MapperHints.java b/mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/reporting/spi/MapperHints.java
@@ -0,0 +1,23 @@
+/*
+ * Hibernate Search, full-text search for your domain model
+ *
+ * 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.search.mapper.pojo.reporting.spi;
+
+import org.hibernate.search.util.common.logging.impl.MessageConstants;
+
+import org.jboss.logging.Messages;
+import org.jboss.logging.annotations.Message;
+import org.jboss.logging.annotations.MessageBundle;
+
+@MessageBundle(projectCode = MessageConstants.PROJECT_CODE)
+public interface MapperHints {
+
+	MapperHints NONE = Messages.getBundle( MapperHints.class );
+
+	@Message("")
+	String cannotReadJandexRootMapping();
+
+}
diff --git a/mapper/pojo-standalone/src/main/java/org/hibernate/search/mapper/pojo/standalone/mapping/impl/StandalonePojoMappingInitiator.java b/mapper/pojo-standalone/src/main/java/org/hibernate/search/mapper/pojo/standalone/mapping/impl/StandalonePojoMappingInitiator.java
@@ -22,6 +22,7 @@
 import org.hibernate.search.mapper.pojo.standalone.mapping.StandalonePojoMappingConfigurationContext;
 import org.hibernate.search.mapper.pojo.standalone.mapping.StandalonePojoMappingConfigurer;
 import org.hibernate.search.mapper.pojo.standalone.model.impl.StandalonePojoBootstrapIntrospector;
+import org.hibernate.search.mapper.pojo.standalone.reporting.impl.StandalonePojoMapperHints;
 
 public class StandalonePojoMappingInitiator extends AbstractPojoMappingInitiator<StandalonePojoMappingPartialBuildState>
 		implements StandalonePojoMappingConfigurationContext {
@@ -40,7 +41,7 @@ public class StandalonePojoMappingInitiator extends AbstractPojoMappingInitiator
 					.build();
 
 	public StandalonePojoMappingInitiator(StandalonePojoBootstrapIntrospector introspector) {
-		super( introspector );
+		super( introspector, StandalonePojoMapperHints.INSTANCE );
 		// Enable annotated type discovery by default
 		annotationMapping()
 				.discoverAnnotatedTypesFromRootMappingAnnotations( true )
diff --git a/mapper/pojo-standalone/src/main/java/org/hibernate/search/mapper/pojo/standalone/reporting/impl/StandalonePojoMapperHints.java b/mapper/pojo-standalone/src/main/java/org/hibernate/search/mapper/pojo/standalone/reporting/impl/StandalonePojoMapperHints.java
@@ -0,0 +1,32 @@
+/*
+ * Hibernate Search, full-text search for your domain model
+ *
+ * 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.search.mapper.pojo.standalone.reporting.impl;
+
+import org.hibernate.search.mapper.pojo.reporting.spi.MapperHints;
+import org.hibernate.search.mapper.pojo.standalone.cfg.StandalonePojoMapperSettings;
+import org.hibernate.search.util.common.logging.impl.MessageConstants;
+
+import org.jboss.logging.Messages;
+import org.jboss.logging.annotations.Message;
+import org.jboss.logging.annotations.MessageBundle;
+
+@MessageBundle(projectCode = MessageConstants.PROJECT_CODE)
+public interface StandalonePojoMapperHints extends MapperHints {
+
+	StandalonePojoMapperHints INSTANCE = Messages.getBundle( StandalonePojoMapperHints.class );
+
+	@Message("Prebuild the missing Jandex indexes and make them available to Hibernate Search"
+			+ " or use a combination of configuration properties ("
+			+ " \"" + StandalonePojoMapperSettings.MAPPING_CONFIGURER + "\","
+			+ " \"" + StandalonePojoMapperSettings.MAPPING_DISCOVER_ANNOTATED_TYPES_FROM_ROOT_MAPPING_ANNOTATIONS + "\","
+			+ " \"" + StandalonePojoMapperSettings.MAPPING_BUILD_MISSING_DISCOVERED_JANDEX_INDEXES + "\""
+			+ ") to limit the discovery of annotated types."
+			+ " For specifics, refer to the \"Classpath scanning\""
+			+ " section of the reference documentation.")
+	String cannotReadJandexRootMapping();
+
+}

Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,7 @@`
`30`	`30`	`import org.hibernate.search.mapper.pojo.mapping.spi.PojoMappingConfigurationContributor;`
`31`	`31`	`import org.hibernate.search.mapper.pojo.model.spi.PojoBootstrapIntrospector;`
`32`	`32`	`import org.hibernate.search.mapper.pojo.model.spi.PojoRawTypeModel;`
	`33`	`+import org.hibernate.search.mapper.pojo.reporting.spi.MapperHints;`
`33`	`34`	`import org.hibernate.search.util.common.jar.impl.JandexUtils;`
`34`	`35`	`import org.hibernate.search.util.common.jar.impl.JarUtils;`
`35`	`36`	`import org.hibernate.search.util.common.jar.spi.JandexBehavior;`
`@@ -49,6 +50,7 @@ public class AnnotationMappingConfigurationContextImpl`
`49`	`50`	`private static final Log log = LoggerFactory.make( Log.class, MethodHandles.lookup() );`
`50`	`51`
`51`	`52`	`private final PojoBootstrapIntrospector introspector;`
	`53`	`+ private final MapperHints mapperHints;`
`52`	`54`
`53`	`55`	`private boolean discoverAnnotatedTypesFromRootMappingAnnotations = false;`
`54`	`56`	`private boolean discoverJandexIndexesFromAddedTypes = false;`
`@@ -59,8 +61,10 @@ public class AnnotationMappingConfigurationContextImpl`
`59`	`61`	`private final Set<Class<?>> explicitAnnotatedTypes = new LinkedHashSet<>();`
`60`	`62`	`private final List<IndexView> explicitJandexIndexes = new ArrayList<>();`
`61`	`63`
`62`		`- public AnnotationMappingConfigurationContextImpl(PojoBootstrapIntrospector introspector) {`
	`64`	`+ public AnnotationMappingConfigurationContextImpl(PojoBootstrapIntrospector introspector,`
	`65`	`+ MapperHints mapperHints) {`
`63`	`66`	`this.introspector = introspector;`
	`67`	`+ this.mapperHints = mapperHints;`
`64`	`68`	`}`
`65`	`69`
`66`	`70`	`@Override`
`@@ -221,7 +225,7 @@ private boolean isJandexBuildingAllowed(Class<?> annotatedType) {`
`221`	`225`	`}`
`222`	`226`	`}`
`223`	`227`
`224`		`- private static Optional<Index> jandexIndexForCodeSourceLocation(URL codeSourceLocation, boolean buildIfMissing) {`
	`228`	`+ private Optional<Index> jandexIndexForCodeSourceLocation(URL codeSourceLocation, boolean buildIfMissing) {`
`225`	`229`	`try {`
`226`	`230`	`if ( buildIfMissing ) {`
`227`	`231`	`return Optional.of( JandexUtils.readOrBuildIndex( codeSourceLocation ) );`
`@@ -231,7 +235,8 @@ private static Optional<Index> jandexIndexForCodeSourceLocation(URL codeSourceLo`
`231`	`235`	`}`
`232`	`236`	`}`
`233`	`237`	`catch (RuntimeException e) {`
`234`		`- throw log.errorDiscoveringJandexIndex( codeSourceLocation, e.getMessage(), e );`
	`238`	`+ throw log.errorDiscoveringJandexIndex( codeSourceLocation, e.getMessage(),`
	`239`	`+ mapperHints.cannotReadJandexRootMapping(), e );`
`235`	`240`	`}`
`236`	`241`	`}`
`237`	`242`