Include the reasons why the check breaks the start

Author: marko-bekhta

extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/BuiltinFormatMapperBehaviour.java

@@ -1,5 +1,6 @@
 package io.quarkus.hibernate.orm.runtime.customized;
 
+import java.util.List;
 import java.util.Locale;
 import java.util.concurrent.atomic.AtomicBoolean;
 
@@ -19,7 +20,7 @@ public enum BuiltinFormatMapperBehaviour {
      */
     IGNORE {
         @Override
-        protected void action(String puName, String type) {
+        protected void action(String puName, String type, List<String> causes) {
         }
     },
     /**
@@ -28,25 +29,25 @@ protected void action(String puName, String type) {
      */
     WARN {
         @Override
-        protected void action(String puName, String type) {
-            LOGGER.warn(message(puName, type));
+        protected void action(String puName, String type, List<String> causes) {
+            LOGGER.warn(message(puName, type, causes));
         }
     },
     /**
      * Currently the default one. If there is no user provided format mapper, a Quarkus preconfigured one will fail at runtime.
      */
     FAIL {
         @Override
-        protected void action(String puName, String type) {
-            throw new IllegalStateException(message(puName, type));
+        protected void action(String puName, String type, List<String> causes) {
+            throw new IllegalStateException(message(puName, type, causes));
         }
     };
 
     private static final Logger LOGGER = Logger.getLogger(BuiltinFormatMapperBehaviour.class);
     private static final String TYPE_JSON = "JSON";
     private static final String TYPE_XML = "XML";
 
-    private static String message(String puName, String type) {
+    private static String message(String puName, String type, List<String> causes) {
         return String.format(Locale.ROOT,
                 "Persistence unit [%1$s] uses Quarkus' main formatting facilities for %2$s columns in the database. "
                         + "\nAs these facilities are primarily meant for REST endpoints, and they might have been customized for such use, "
@@ -58,6 +59,8 @@ private static String message(String puName, String type) {
                         + " and @PersistenceUnitExtension"
                         + (PersistenceUnitUtil.isDefaultPersistenceUnit(puName) ? "" : "(\"%1$s\")")
                         + " to address your database serialization/deserialization needs."
+                        + "\nThe reasons why the check was triggered are: \n\t-"
+                        + String.join("\n\t-", causes)
                         + "\nSee the migration guide for more details and how to proceed.",
                 puName, type);
     }
@@ -94,8 +97,11 @@ public static boolean hasXmlProperties(MetadataImplementor metadata) {
 
     public void jsonApply(MetadataImplementor metadata, String puName, ArcContainer container,
             JsonFormatterCustomizationCheck check) {
-        if (hasJsonProperties(metadata) && check.test(container)) {
-            action(puName, TYPE_JSON);
+        if (hasJsonProperties(metadata)) {
+            List<String> causes = check.apply(container);
+            if (!causes.isEmpty()) {
+                action(puName, TYPE_JSON, causes);
+            }
         }
     }
 
@@ -110,9 +116,10 @@ public void xmlApply(MetadataImplementor metadata, String puName) {
         // Let's fail and tell the user to migrate their data to the new format and before that is done: use a delegate to org.hibernate.type.format.jaxb.JaxbXmlFormatMapper()
         // using a legacy format:
         if (hasXmlProperties(metadata)) {
-            action(puName, TYPE_XML);
+            action(puName, TYPE_XML,
+                    List.of("The XML format mapper uses the legacy format. It is not compatible with the new default one."));
         }
     }
 
-    protected abstract void action(String puName, String type);
+    protected abstract void action(String puName, String type, List<String> causes);
 }

extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/JsonFormatterCustomizationCheck.java

@@ -1,8 +1,10 @@
 package io.quarkus.hibernate.orm.runtime.customized;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
-import java.util.function.Predicate;
+import java.util.function.Function;
 
 import jakarta.enterprise.inject.Instance;
 import jakarta.json.bind.Jsonb;
@@ -20,9 +22,9 @@
  * Test whether the underlying Jackson Object Mapper / JSON-B used to create the "built-in" format mapper
  * were modified and cannot be safely replaced by the Hibernate ORM's default ones.
  */
-public interface JsonFormatterCustomizationCheck extends Predicate<ArcContainer> {
+public interface JsonFormatterCustomizationCheck extends Function<ArcContainer, List<String>> {
     @Override
-    boolean test(ArcContainer container);
+    List<String> apply(ArcContainer container);
 
     static JsonFormatterCustomizationCheck jsonFormatterCustomizationCheckSupplier(boolean required, boolean isJackson) {
         if (!required) {
@@ -37,22 +39,24 @@ static JsonFormatterCustomizationCheck jsonFormatterCustomizationCheckSupplier(b
 
     class NotModifiedJsonFormatterCustomizationCheck implements JsonFormatterCustomizationCheck {
         @Override
-        public boolean test(ArcContainer container) {
-            return false;
+        public List<String> apply(ArcContainer container) {
+            return List.of();
         }
     }
 
     class JacksonJsonFormatterCustomizationCheck implements JsonFormatterCustomizationCheck {
         @Override
-        public boolean test(ArcContainer container) {
+        public List<String> apply(ArcContainer container) {
             InstanceHandle<ObjectMapper> objectMapperInstance = container.instance(ObjectMapper.class);
             if (!objectMapperInstance.isAvailable()) {
                 // We have no mapper so it wasn't modified, and we've probably used the JSONB instead.
-                return false;
+                return List.of();
             }
+            List<String> causes = new ArrayList<>();
             if (!objectMapperInstance.getBean().isDefaultBean()) {
                 // A bean producer was used and the ObjectMapper is a user custom bean...
-                return true;
+                causes.add(
+                        "ObjectMapper instance is not the Quarkus default one. A bean producer was likely used to replace it.");
             }
 
             Instance<ObjectMapperCustomizer> customizers = container.select(ObjectMapperCustomizer.class);
@@ -70,7 +74,8 @@ public boolean test(ArcContainer container) {
                         continue;
                     }
                     // ObjectMapper was potentially customized
-                    return true;
+                    causes.add("Detected '" + handle.getBean().getBeanClass().getName() + "' bean registered. "
+                            + "It may have customized the ObjectMapper in a way not compatible with the default one.");
                 }
             }
 
@@ -87,26 +92,30 @@ public boolean test(ArcContainer container) {
                     String okValue = expectedDefaults.get(propertyName);
                     if (okValue != null && !okValue
                             .equalsIgnoreCase(ConfigProvider.getConfig().getConfigValue(propertyName).getRawValue())) {
-                        return true;
+                        causes.add("Detected '" + propertyName + "' property set to '"
+                                + ConfigProvider.getConfig().getConfigValue(propertyName).getRawValue() + "'. "
+                                + "For ObjectMapper being compatible with the clean, default one the expected value is: '"
+                                + okValue + "'.");
                     }
                 }
             }
 
-            return false;
+            return causes;
         }
     }
 
     class JsonbJsonFormatterCustomizationCheck implements JsonFormatterCustomizationCheck {
         @Override
-        public boolean test(ArcContainer container) {
+        public List<String> apply(ArcContainer container) {
             InstanceHandle<Jsonb> jsonbInstance = container.instance(Jsonb.class);
             if (!jsonbInstance.isAvailable()) {
                 // We have no JSON-B bean so it wasn't modified.
-                return false;
+                return List.of();
             }
+            List<String> causes = new ArrayList<>();
             if (!jsonbInstance.getBean().isDefaultBean()) {
                 // A bean producer was used and the JSON-B is a user custom bean...
-                return true;
+                causes.add("Jsonb instance is not the Quarkus default one. A bean producer was likely used to replace it.");
             }
 
             Instance<JsonbConfigCustomizer> customizers = container.select(JsonbConfigCustomizer.class);
@@ -120,11 +129,12 @@ public boolean test(ArcContainer container) {
                 }
 
                 // JSON-B was potentially customized
-                return true;
+                causes.add("Detected '" + handle.getBean().getBeanClass().getName() + "' bean registered. "
+                        + "It may have customized the Jsonb in a way not compatible with the default one.");
             }
 
             // JSON-B does not have the config properties so nothing else to check..
-            return false;
+            return causes;
         }
     }
 }