This is an automated email from the ASF dual-hosted git repository.

Croway pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/main by this push:
     new c06d4ebd7739 CAMEL-27115: camel-core - log a WARN on startup when type 
converters on the classpath are not loaded
c06d4ebd7739 is described below

commit c06d4ebd77396b0c6765fe44a8132b1a41f7d527
Author: croway <[email protected]>
AuthorDate: Tue Nov 17 15:43:00 2026 +0100

    CAMEL-27115: camel-core - log a WARN on startup when type converters on the 
classpath are not loaded
    
    A META-INF/services/org/apache/camel/TypeConverter file is not read while
    loadTypeConverters is off, and a fat jar that kept the TypeConverterLoader 
file
    of another Camel JAR has no core converters. Both now log a WARN with the 
file
    locations and the fix (loadTypeConverters, @Converter(generateLoader = 
true),
    the prepare-fatjar goal). Loading does not change.
---
 .../impl/converter/BaseTypeConverterRegistry.java  |  16 ++
 .../camel/impl/converter/DefaultTypeConverter.java |  50 ++++-
 .../TypeConverterFilesNotLoadedWarningTest.java    | 233 +++++++++++++++++++++
 .../modules/ROOT/pages/type-converter.adoc         |  24 +++
 4 files changed, 321 insertions(+), 2 deletions(-)

diff --git 
a/core/camel-base/src/main/java/org/apache/camel/impl/converter/BaseTypeConverterRegistry.java
 
b/core/camel-base/src/main/java/org/apache/camel/impl/converter/BaseTypeConverterRegistry.java
index 5daec0415626..867a7a86e8ef 100644
--- 
a/core/camel-base/src/main/java/org/apache/camel/impl/converter/BaseTypeConverterRegistry.java
+++ 
b/core/camel-base/src/main/java/org/apache/camel/impl/converter/BaseTypeConverterRegistry.java
@@ -35,6 +35,7 @@ import org.apache.camel.NoFactoryAvailableException;
 import org.apache.camel.RuntimeCamelException;
 import org.apache.camel.TypeConverter;
 import org.apache.camel.TypeConverterLoaderException;
+import org.apache.camel.converter.CamelBaseBulkConverterLoader;
 import org.apache.camel.spi.Injector;
 import org.apache.camel.spi.PackageScanClassResolver;
 import org.apache.camel.spi.TypeConverterLoader;
@@ -59,10 +60,14 @@ public abstract class BaseTypeConverterRegistry extends 
CoreTypeConverterRegistr
 
     private static final Logger LOG = 
LoggerFactory.getLogger(BaseTypeConverterRegistry.class);
 
+    // the loader of the core type converters, which every Camel application 
needs
+    private static final String CORE_TYPE_CONVERTER_LOADER = 
CamelBaseBulkConverterLoader.class.getName();
+
     protected final List<TypeConverterLoader> typeConverterLoaders = new 
ArrayList<>();
     protected CamelContext camelContext;
     protected PackageScanClassResolver resolver;
     protected Injector injector;
+    private boolean coreTypeConverterLoaderWarned;
 
     protected BaseTypeConverterRegistry(CamelContext camelContext, 
PackageScanClassResolver resolver, Injector injector,
                                         boolean statisticsEnabled) {
@@ -144,6 +149,17 @@ public abstract class BaseTypeConverterRegistry extends 
CoreTypeConverterRegistr
     public void loadCoreAndFastTypeConverters() throws Exception {
         Collection<String> names = findTypeConverterLoaderClasses();
 
+        if (!coreTypeConverterLoaderWarned && 
!names.contains(CORE_TYPE_CONVERTER_LOADER)) {
+            coreTypeConverterLoaderWarned = true;
+            LOG.warn("Type converter loader {} is not listed in any {} file on 
the classpath (found: {}),"
+                     + " so the core type converters of camel-base (such as 
String to Integer or Duration) are not loaded."
+                     + " A fat jar keeps only one of these files unless they 
are merged:"
+                     + " build it with the prepare-fatjar goal of the 
camel-maven-plugin,"
+                     + " or merge the {} files of the Camel JARs.",
+                    CORE_TYPE_CONVERTER_LOADER, 
META_INF_SERVICES_TYPE_CONVERTER_LOADER,
+                    getLoaderUrls(META_INF_SERVICES_TYPE_CONVERTER_LOADER), 
META_INF_SERVICES_TYPE_CONVERTER_LOADER);
+        }
+
         for (String name : names) {
             LOG.debug("Resolving TypeConverterLoader: {}", name);
             Class<?> clazz = null;
diff --git 
a/core/camel-base/src/main/java/org/apache/camel/impl/converter/DefaultTypeConverter.java
 
b/core/camel-base/src/main/java/org/apache/camel/impl/converter/DefaultTypeConverter.java
index cfc8fde285cf..f82a74fa74b0 100644
--- 
a/core/camel-base/src/main/java/org/apache/camel/impl/converter/DefaultTypeConverter.java
+++ 
b/core/camel-base/src/main/java/org/apache/camel/impl/converter/DefaultTypeConverter.java
@@ -16,6 +16,11 @@
  */
 package org.apache.camel.impl.converter;
 
+import java.io.IOException;
+import java.net.URL;
+import java.util.LinkedHashSet;
+import java.util.Set;
+
 import org.apache.camel.CamelContext;
 import org.apache.camel.spi.AnnotationScanTypeConverters;
 import org.apache.camel.spi.Injector;
@@ -38,6 +43,8 @@ public class DefaultTypeConverter extends 
BaseTypeConverterRegistry implements A
 
     private volatile boolean loadTypeConvertersDone;
     private final boolean loadTypeConverters;
+    private Set<String> typeConverterFiles;
+    private boolean typeConverterFilesWarned;
 
     public DefaultTypeConverter(PackageScanClassResolver resolver, Injector 
injector,
                                 boolean loadTypeConverters, boolean 
statisticsEnabled) {
@@ -73,6 +80,46 @@ public class DefaultTypeConverter extends 
BaseTypeConverterRegistry implements A
         }
     }
 
+    @Override
+    public void loadCoreAndFastTypeConverters() throws Exception {
+        super.loadCoreAndFastTypeConverters();
+
+        // the META-INF/services/org/apache/camel/TypeConverter files are only 
read when scanning for type converters,
+        // remember them to warn on startup if scanning is turned off 
(runtimes that discover the converters at build
+        // time override this method, and do not get the warning)
+        Set<String> files = new LinkedHashSet<>();
+        try {
+            for (URL url : 
getLoaderUrls(AnnotationTypeConverterLoader.META_INF_SERVICES)) {
+                files.add(url.toString());
+            }
+        } catch (IOException e) {
+            LOG.debug("Cannot find {} files due to: {}", 
AnnotationTypeConverterLoader.META_INF_SERVICES, e.getMessage(), e);
+        }
+        typeConverterFiles = files;
+    }
+
+    @Override
+    protected void doStart() throws Exception {
+        super.doStart();
+
+        // loadTypeConverters can be set after this type converter is 
initialized (such as by camel-main),
+        // so check on startup
+        if (!typeConverterFilesWarned && !loadTypeConvertersDone && 
typeConverterFiles != null
+                && !typeConverterFiles.isEmpty() && !isLoadTypeConverters() && 
getBasePackageScan() == null) {
+            typeConverterFilesWarned = true;
+            LOG.warn("Type converter file {} found at {} is not read, because 
scanning the classpath for type converters"
+                     + " is turned off, so the @Converter classes it lists are 
not loaded."
+                     + " Set camel.main.loadTypeConverters=true (or 
setLoadTypeConverters(true) on the CamelContext),"
+                     + " or annotate the converter classes with 
@Converter(generateLoader = true) and build them with the"
+                     + " camel-component-maven-plugin, or add them with 
addTypeConverters on the TypeConverterRegistry.",
+                    AnnotationTypeConverterLoader.META_INF_SERVICES, 
String.join(", ", typeConverterFiles));
+        }
+    }
+
+    private String getBasePackageScan() {
+        return camelContext != null ? 
camelContext.getCamelContextExtension().getBasePackageScan() : null;
+    }
+
     private boolean isLoadTypeConverters() {
         boolean load = loadTypeConverters;
         if (camelContext != null) {
@@ -111,7 +158,6 @@ public class DefaultTypeConverter extends 
BaseTypeConverterRegistry implements A
      * Creates the {@link TypeConverterLoader} to use for scanning for type 
converters such as from the classpath.
      */
     protected TypeConverterLoader createScanTypeConverterLoader() {
-        String basePackages = camelContext != null ? 
camelContext.getCamelContextExtension().getBasePackageScan() : null;
-        return new AnnotationTypeConverterLoader(resolver, basePackages);
+        return new AnnotationTypeConverterLoader(resolver, 
getBasePackageScan());
     }
 }
diff --git 
a/core/camel-core/src/test/java/org/apache/camel/impl/converter/TypeConverterFilesNotLoadedWarningTest.java
 
b/core/camel-core/src/test/java/org/apache/camel/impl/converter/TypeConverterFilesNotLoadedWarningTest.java
new file mode 100644
index 000000000000..d5b4e010b84d
--- /dev/null
+++ 
b/core/camel-core/src/test/java/org/apache/camel/impl/converter/TypeConverterFilesNotLoadedWarningTest.java
@@ -0,0 +1,233 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.impl.converter;
+
+import java.io.IOException;
+import java.net.URL;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+import org.apache.camel.TypeConverter;
+import org.apache.camel.impl.DefaultCamelContext;
+import org.apache.camel.processor.converter.custom.MyBean;
+import org.apache.camel.support.PluginHelper;
+import org.apache.logging.log4j.Level;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.LogEvent;
+import org.apache.logging.log4j.core.LoggerContext;
+import org.apache.logging.log4j.core.appender.AbstractAppender;
+import org.apache.logging.log4j.core.config.Property;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.api.parallel.Isolated;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Camel logs a WARN on startup when type converters on the classpath are not 
loaded: a
+ * META-INF/services/org/apache/camel/TypeConverter file while 
loadTypeConverters is off, or no
+ * META-INF/services/org/apache/camel/TypeConverterLoader file that lists the 
core converters of camel-base (a fat jar
+ * that kept the file of another Camel JAR).
+ * <p>
+ * The camel-core test classpath has a 
META-INF/services/org/apache/camel/TypeConverter file that lists the package of
+ * {@link org.apache.camel.processor.converter.custom.MyConverter}, which 
converts "a:b" to a {@link MyBean}.
+ * <p>
+ * Isolated because other test classes start contexts that log the same WARN.
+ */
+@Isolated
+public class TypeConverterFilesNotLoadedWarningTest {
+
+    private static final String LEGACY_FILE = 
AnnotationTypeConverterLoader.META_INF_SERVICES;
+    private static final String LOADER_FILE = 
BaseTypeConverterRegistry.META_INF_SERVICES_TYPE_CONVERTER_LOADER;
+    private static final String UBER_LOADER_FILE = 
BaseTypeConverterRegistry.META_INF_SERVICES_UBER_TYPE_CONVERTER_LOADER;
+    private static final String CORE_LOADER = 
"org.apache.camel.converter.CamelBaseBulkConverterLoader";
+    private static final String SUPPORT_LOADER = 
"org.apache.camel.converter.stream.CamelSupportBulkConverterLoader";
+
+    private final List<String> warnings = new CopyOnWriteArrayList<>();
+    private AbstractAppender appender;
+
+    @TempDir
+    Path dir;
+
+    @BeforeEach
+    public void captureWarnings() {
+        appender = new AbstractAppender(
+                "type-converter-warnings-" + UUID.randomUUID(), null, null, 
true,
+                Property.EMPTY_ARRAY) {
+            @Override
+            public void append(LogEvent event) {
+                if (event.getLevel().isMoreSpecificThan(Level.WARN)
+                        && 
event.getLoggerName().startsWith("org.apache.camel.impl.converter")) {
+                    warnings.add(event.getMessage().getFormattedMessage());
+                }
+            }
+        };
+        appender.start();
+        LoggerContext logging = (LoggerContext) LogManager.getContext(false);
+        logging.getConfiguration().getRootLogger().addAppender(appender, 
Level.WARN, null);
+        logging.updateLoggers();
+    }
+
+    @AfterEach
+    public void stopCapture() {
+        LoggerContext logging = (LoggerContext) LogManager.getContext(false);
+        
logging.getConfiguration().getRootLogger().removeAppender(appender.getName());
+        logging.updateLoggers();
+        appender.stop();
+    }
+
+    @Test
+    public void typeConverterFileNotReadLogsWarning() throws Exception {
+        URL url = getClass().getClassLoader().getResource(LEGACY_FILE);
+        assertNotNull(url, "the test classpath should have " + LEGACY_FILE);
+
+        try (DefaultCamelContext context = new DefaultCamelContext()) {
+            context.start();
+
+            // the behaviour is unchanged: the converters listed in the file 
are not loaded
+            assertNull(context.getTypeConverter().convertTo(MyBean.class, 
"a:b"));
+
+            List<String> legacy = warnings.stream().filter(w -> 
w.contains(LEGACY_FILE)).toList();
+            assertEquals(1, legacy.size(), warnings.toString());
+            String warning = legacy.get(0);
+            assertTrue(warning.contains(url.toString()), warning);
+            assertTrue(warning.contains("camel.main.loadTypeConverters=true"), 
warning);
+            assertTrue(warning.contains("@Converter(generateLoader = true)"), 
warning);
+
+            // logged once on startup, not on each conversion
+            assertNull(context.getTypeConverter().convertTo(MyBean.class, 
"c:d"));
+            assertEquals(1, warnings.stream().filter(w -> 
w.contains(LEGACY_FILE)).count(), warnings.toString());
+        }
+    }
+
+    @Test
+    public void loadTypeConvertersEnabledBeforeStartReadsFileWithoutWarning() 
throws Exception {
+        try (DefaultCamelContext context = new DefaultCamelContext()) {
+            // enabled after the type converter is initialized, as camel-main 
and Spring do
+            context.setLoadTypeConverters(true);
+            context.start();
+
+            assertEquals(new MyBean("a", "b"), 
context.getTypeConverter().convertTo(MyBean.class, "a:b"));
+            assertTrue(warnings.isEmpty(), warnings.toString());
+        }
+    }
+
+    @Test
+    public void basePackageScanReadsFileWithoutWarning() throws Exception {
+        try (DefaultCamelContext context = new DefaultCamelContext()) {
+            
context.getCamelContextExtension().setBasePackageScan("org.apache.camel.processor.converter.custom");
+            context.start();
+
+            assertEquals(new MyBean("a", "b"), 
context.getTypeConverter().convertTo(MyBean.class, "a:b"));
+            assertTrue(warnings.isEmpty(), warnings.toString());
+        }
+    }
+
+    @Test
+    public void noWarningWithoutTypeConverterFile() throws Exception {
+        try (DefaultCamelContext context = contextWithLoaderFiles(Map.of())) {
+            context.start();
+
+            assertEquals(5, 
context.getTypeConverter().convertTo(Integer.class, "5"));
+            assertTrue(warnings.isEmpty(), warnings.toString());
+        }
+    }
+
+    @Test
+    public void coreLoaderMissingLogsWarning() throws Exception {
+        // a fat jar that kept the TypeConverterLoader file of camel-support 
only
+        URL loaderFile = writeFile("TypeConverterLoader", SUPPORT_LOADER);
+
+        try (DefaultCamelContext context = 
contextWithLoaderFiles(Map.of(LOADER_FILE, loaderFile))) {
+            context.start();
+
+            // the behaviour is unchanged: the core converters are not loaded
+            assertNull(context.getTypeConverter().convertTo(Integer.class, 
"5"));
+            assertNull(context.getTypeConverter().convertTo(Duration.class, 
"0"));
+
+            List<String> core = warnings.stream().filter(w -> 
w.contains(CORE_LOADER)).toList();
+            assertEquals(1, core.size(), warnings.toString());
+            String warning = core.get(0);
+            assertTrue(warning.contains(loaderFile.toString()), warning);
+            assertTrue(warning.contains("prepare-fatjar"), warning);
+
+            // logged once on startup, not on each conversion
+            assertNull(context.getTypeConverter().convertTo(Integer.class, 
"6"));
+            assertEquals(1, warnings.stream().filter(w -> 
w.contains(CORE_LOADER)).count(), warnings.toString());
+        }
+    }
+
+    @Test
+    public void uberLoaderFileListsCoreLoaderWithoutWarning() throws Exception 
{
+        // a fat jar built with camel:prepare-fatjar: the uber file lists all 
the loaders
+        URL loaderFile = writeFile("TypeConverterLoader", SUPPORT_LOADER);
+        URL uberFile = writeFile("UberTypeConverterLoader", CORE_LOADER + "\n" 
+ SUPPORT_LOADER);
+
+        try (DefaultCamelContext context
+                = contextWithLoaderFiles(Map.of(LOADER_FILE, loaderFile, 
UBER_LOADER_FILE, uberFile))) {
+            context.start();
+
+            assertEquals(5, 
context.getTypeConverter().convertTo(Integer.class, "5"));
+            assertEquals(Duration.ZERO, 
context.getTypeConverter().convertTo(Duration.class, "0"));
+            assertTrue(warnings.isEmpty(), warnings.toString());
+        }
+    }
+
+    private URL writeFile(String name, String content) throws IOException {
+        Path file = dir.resolve(name);
+        Files.writeString(file, content + "\n");
+        return file.toUri().toURL();
+    }
+
+    /**
+     * A context whose type converter sees only the given service files, and 
the real TypeConverterLoader files when
+     * none is given for that path.
+     */
+    private static DefaultCamelContext contextWithLoaderFiles(Map<String, URL> 
files) {
+        return new DefaultCamelContext() {
+            @Override
+            protected TypeConverter createTypeConverter() {
+                return new DefaultTypeConverter(
+                        this, PluginHelper.getPackageScanClassResolver(this), 
getInjector(), isLoadTypeConverters(),
+                        false) {
+                    @Override
+                    protected Collection<URL> getLoaderUrls(String basePath) 
throws IOException {
+                        URL url = files.get(basePath);
+                        if (url != null) {
+                            return List.of(url);
+                        }
+                        if (LOADER_FILE.equals(basePath)) {
+                            return super.getLoaderUrls(basePath);
+                        }
+                        return List.of();
+                    }
+                };
+            }
+        };
+    }
+}
diff --git a/docs/user-manual/modules/ROOT/pages/type-converter.adoc 
b/docs/user-manual/modules/ROOT/pages/type-converter.adoc
index 38201449f5c8..fb95a58aa5e3 100644
--- a/docs/user-manual/modules/ROOT/pages/type-converter.adoc
+++ b/docs/user-manual/modules/ROOT/pages/type-converter.adoc
@@ -207,6 +207,30 @@ The following code shows snippet of the source code 
generated bulk class. As you
             }
 ----
 
+=== Discovering Type Converters by scanning the classpath
+
+Converter classes without a generated loader can be listed in a 
`META-INF/services/org/apache/camel/TypeConverter`
+file, with one package or class name per line. Camel reads this file only when 
scanning the classpath for type converters
+is turned on, which is off by default:
+
+[source,properties]
+----
+camel.main.loadTypeConverters = true
+----
+
+When scanning is off and Camel finds such a file, it logs a WARN on startup 
with the location of the file.
+Prefer `@Converter(generateLoader = true)`, which needs no scanning.
+
+=== Type Converters in a fat jar
+
+Each Camel JAR has its own 
`META-INF/services/org/apache/camel/TypeConverterLoader` file.
+A fat jar (such as one built with `maven-assembly-plugin`) keeps only one of 
these files unless the build merges them.
+The core type converters of `camel-base` are then not loaded, and conversions 
such as `String` to `Integer` or
+`Duration` fail. Camel logs a WARN on startup when no loader file lists the 
core converters.
+
+Build the fat jar with the `camel:prepare-fatjar` goal of the 
xref:camel-maven-plugin.adoc[Camel Maven Plugin],
+which writes one file that lists the type converter loaders of all the JARs.
+
 === Returning null values
 
 By default, when using a method in a POJO annotation with `@Converter`

Reply via email to