gnodet-bot commented on code in PR #30386:
URL: https://github.com/apache/camel/pull/30386#discussion_r4626859759


##########
dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/common/CommandMetadataRegistry.java:
##########
@@ -0,0 +1,92 @@
+/*
+ * 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.dsl.jbang.core.common;
+
+import java.util.Set;
+
+import org.aesh.command.metadata.CommandMetadataProvider;
+import org.aesh.command.metadata.MetadataRegistry;
+
+/**
+ * The aesh metadata of the commands in the given packages, which the aesh 
annotation processor generates at compile
+ * time: aesh then does not read the annotations of a command at run time, 
which creates a proxy class for each kind of
+ * annotation.
+ * <p>
+ * The metadata of a command is the class {@code <command class>_AeshMetadata} 
in the package of the command (a nested
+ * class {@code Outer$Inner} has {@code Outer_Inner_AeshMetadata}). The 
registry that the processor generates is not
+ * used, as it is in the package of the command that the processor happens to 
see first.
+ * <p>
+ * Only the commands of the given packages are looked up: all the commands of 
the CLI and its plugins are in packages of
+ * {@code org.apache.camel.dsl.jbang.core.commands}, and a class that is not 
there costs a search of the whole class
+ * path.
+ * <p>
+ * aesh looks up the metadata of a command class, and then of its super 
classes, so a command without metadata of its
+ * own gets the metadata of the command it extends, which misses its own 
options. A command that a plugin extends with
+ * options of its own (Export, by KubernetesExport) is therefore excluded: 
aesh reads the annotations of both at run
+ * time. CommandTree fails when a command would get the metadata of its super 
class while it has options of its own.
+ * <p>
+ * Not a record: the equals of a record (which aesh calls when the registry is 
set) starts the method handles of the JDK
+ * (about 200 classes), which costs more than the metadata saves on a short 
command.
+ */

Review Comment:
   **Low** — The `Not a record` rationale in the class Javadoc correctly 
explains the design, but it ties a future reader's understanding to a JDK 
implementation detail (method handle bootstrapping cost). Consider adding a 
brief inline note at the class declaration itself — e.g. `// do not convert to 
record — see Javadoc` — so anyone who tries to refactor hits the explanation 
immediately without having to trace back to the class comment.



##########
dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/common/CommandMetadataRegistry.java:
##########
@@ -0,0 +1,92 @@
+/*
+ * 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.dsl.jbang.core.common;
+
+import java.util.Set;
+
+import org.aesh.command.metadata.CommandMetadataProvider;
+import org.aesh.command.metadata.MetadataRegistry;
+
+/**
+ * The aesh metadata of the commands in the given packages, which the aesh 
annotation processor generates at compile
+ * time: aesh then does not read the annotations of a command at run time, 
which creates a proxy class for each kind of
+ * annotation.
+ * <p>
+ * The metadata of a command is the class {@code <command class>_AeshMetadata} 
in the package of the command (a nested
+ * class {@code Outer$Inner} has {@code Outer_Inner_AeshMetadata}). The 
registry that the processor generates is not
+ * used, as it is in the package of the command that the processor happens to 
see first.
+ * <p>
+ * Only the commands of the given packages are looked up: all the commands of 
the CLI and its plugins are in packages of
+ * {@code org.apache.camel.dsl.jbang.core.commands}, and a class that is not 
there costs a search of the whole class
+ * path.
+ * <p>
+ * aesh looks up the metadata of a command class, and then of its super 
classes, so a command without metadata of its
+ * own gets the metadata of the command it extends, which misses its own 
options. A command that a plugin extends with
+ * options of its own (Export, by KubernetesExport) is therefore excluded: 
aesh reads the annotations of both at run
+ * time. CommandTree fails when a command would get the metadata of its super 
class while it has options of its own.
+ * <p>
+ * Not a record: the equals of a record (which aesh calls when the registry is 
set) starts the method handles of the JDK
+ * (about 200 classes), which costs more than the metadata saves on a short 
command.
+ */
+public final class CommandMetadataRegistry implements MetadataRegistry {
+
+    private static final String SUFFIX = "_AeshMetadata";
+
+    private final ClassLoader classLoader;
+    private final Set<String> packages;
+    private final Set<String> excluded;
+
+    /**
+     * @param classLoader the class loader of the commands
+     * @param packages    the packages of the commands
+     * @param excluded    the classes to read the annotations of at run time 
(and their super classes without metadata)
+     */
+    public CommandMetadataRegistry(ClassLoader classLoader, Set<String> 
packages, Set<String> excluded) {
+        this.classLoader = classLoader;
+        this.packages = packages;
+        this.excluded = excluded;
+    }
+
+    public Set<String> excluded() {
+        return excluded;
+    }
+
+    @Override
+    public CommandMetadataProvider<?> get(String commandClassName) {
+        int dot = commandClassName.lastIndexOf('.');
+        if (dot < 0 || !packages.contains(commandClassName.substring(0, dot)) 
|| excluded.contains(commandClassName)) {
+            return null;
+        }
+        String simpleName = commandClassName.substring(dot + 1);
+        int nested = simpleName.indexOf('$');
+        if (nested >= 0 && nested + 1 < simpleName.length() && 
Character.isDigit(simpleName.charAt(nested + 1))) {
+            // an anonymous or local class has no metadata of its own (aesh 
uses the one of its super class)
+            return null;
+        }
+        // String.concat, not +: the first string concatenation with + starts 
the method handles of the JDK (about 200
+        // classes), which costs more than the metadata saves on a short 
command
+        String name = commandClassName.substring(0, dot + 
1).concat(simpleName.replace('$', '_')).concat(SUFFIX);

Review Comment:
   **Low** — The `String.concat` comment accurately documents the rationale. 
Consider augmenting it with the measured delta (e.g. "saves ~Xms on first 
invocation" from your profiling), so future readers can decide whether the 
trade-off remains worth it after a JDK upgrade rather than taking the 
optimization on faith.



##########
docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc:
##########
@@ -2009,7 +2009,10 @@ A plugin of the Camel CLI (an implementation of 
`org.apache.camel.dsl.jbang.core
 built for Camel 4.24:
 
 * `Plugin.customize` takes a `CommandTree` instead of a picocli `CommandLine`. 
A command is added with
-  `commandLine.addSubcommand("mycommand", new CommandTree(new 
MyCommand(main)))`.
+  `commandLine.addSubcommand("mycommand", new CommandTree(main.command(new 
MyCommand())))`.
+* A command that extends `CamelCommand` has a no-arg constructor: the 
constructor with the `CamelJBangMain` is removed.
+  The main is set after the command is created, with `main.command(new 
MyCommand())`, and `getMain()` fails when it was
+  not set. The CLI generates the aesh metadata of its commands at compile 
time, which needs the no-arg constructor.
 * The command classes use the aesh annotations: `@CommandDefinition` instead 
of `@Command` (the `footer` of the help

Review Comment:
   **Low** — The paragraph correctly describes the breaking change. Naming the 
exception type explicitly makes it more searchable when plugin authors debug a 
failed startup:
   
   ```suggestion
   * A command that extends `CamelCommand` has a no-arg constructor: the 
constructor with the `CamelJBangMain` is removed.
     The main is set after the command is created, with `main.command(new 
MyCommand())`, and `getMain()` throws
     `IllegalStateException` when it was not set. The CLI generates the aesh 
metadata of its commands at compile time,
     which needs the no-arg constructor.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to