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]
