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`