CAMEL-24500: camel-debug-starter does not open a JMX connector by default

[Croway]

Fixes CAMEL-24500.

What

camel.debug.jmx-connector-enabled now defaults to false in camel-debug-starter.

Adding the starter to the classpath still installs and enables the BacklogDebugger — that is what the starter is for, and asking for a dependency named debug is the operator's intent to debug. It no longer also creates an RMI registry and a JMX RMI server on camel.debug.jmx-connector-port (1099).

Why

CamelDebugAutoConfiguration is @ConditionalOnProperty(matchIfMissing = true) and CamelDebugConfigurationProperties.enabled defaults to true, with standby false. DefaultConfigurationConfigurer.configureBacklogDebugger returns early only when the debugger is neither enabled nor in standby, so with the starter present it always reached:

if (config.isJmxConnectorEnabled()) {
    DebuggerJmxConnectorService connector = new DebuggerJmxConnectorService();
    connector.setCreateConnector(true);
    connector.setRegistryPort(config.getJmxConnectorPort());
    camelContext.addService(connector);
}

Opening a listening socket is a second effect beyond installing the debugger, and nothing in the dependency name says so. camel-main reaches the same code only after camel.debug.enabled is explicitly turned on (it defaults to false there), so the connector is always the result of a deliberate camel.debug.* setting; in the starter, the jar alone was enough. The connector is created with JMXConnectorServerFactory.newJMXConnectorServer(url, null, server) — no authentication and no transport security — and 1099 is the well-known RMI registry port, so it can also collide with an application's own JMX registry.

Why not default enabled to false (or standby to true)

That was the alternative in the ticket. It was not taken because it would break the reason the starter exists: camel-debug-starter is only ever added on purpose, and a debugger that does nothing after being added is a worse default than one that debugs but does not listen. Defaulting jmxConnectorEnabled to false keeps the starter useful out of the box and removes the only effect that reaches outside the process.

Behaviour change and how to opt back in

Tooling that attaches to the debugger from another process — the IntelliJ IDEA and VS Code Camel plugins — needs the connector and must now request it:

camel.debug.jmx-connector-enabled = true
camel.debug.jmx-connector-port = 1099

The starter docs now state that the connector is unauthenticated and must be bound to loopback or firewalled.

camel debug from Camel JBang is unaffected: Debug.doRunDebugSpringBoot adds camel-cli-connector-starter and drives the application through the local CLI connector, not through JMX. It never set camel.debug.jmxConnector*.

An upgrade-guide entry for docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_23.adoc in apache/camel has been drafted and will be raised separately.

Tests

New in components-starter/camel-debug-starter:

• CamelDebugAutoConfigurationDefaultTest — the debugger is installed and enabled, isJmxConnectorEnabled() is false on both the starter properties and the DebuggerConfigurationProperties bean, and camelContext.hasService(DebuggerJmxConnectorService.class) is null, so no connector is started.
• CamelDebugAutoConfigurationJmxConnectorTest — with camel.debug.jmx-connector-enabled=true on a free port, the DebuggerJmxConnectorService is present and started, and the port accepts a TCP connection (awaited with Awaitility).

mvn install -pl components-starter/camel-debug-starter → BUILD SUCCESS, Tests run: 5, Failures: 0, Errors: 0, Skipped: 0.

Regenerated by the module build and committed: src/main/docs/debug.json and docs/spring-boot/modules/ROOT/pages/starters/debug.adoc.

Claude Code (Opus 5) on behalf of Federico Mariani