gnodet-bot commented on code in PR #13612:
URL: https://github.com/apache/maven/pull/13612#discussion_r4350385008
##########
api/maven-api-core/src/main/java/org/apache/maven/api/Session.java:
##########
@@ -217,6 +221,73 @@ default Map<String, String> getEffectiveProperties() {
@Nonnull
Collection<Listener> getListeners();
+ /**
+ * Calculates a lifecycle plan that can be inspected before execution.
+ *
+ * @param project the project for which to calculate the plan
+ * @param tasks lifecycle phases or plugin goals used to calculate the plan
+ * @return the lifecycle planning result
+ * @since 4.1.0
+ */
+ @Nonnull
+ default LifecyclePlanResult planLifecycle(@Nonnull Project project,
@Nonnull List<String> tasks) {
+ return getService(LifecycleExecutor.class).plan(this, project, tasks);
+ }
+
+ /**
+ * Executes a previously calculated lifecycle plan.
+ *
+ * @param plan the lifecycle plan to execute
+ * @return the lifecycle execution result
+ * @since 4.1.0
+ */
+ @Nonnull
+ default LifecycleExecutionResult executeLifecycle(@Nonnull LifecyclePlan
plan) {
Review Comment:
⚠️ **Missing `@throws` tags** — `executeLifecycle(LifecyclePlan)` delegates
to `LifecycleExecutor.execute()` which declares `@throws
LifecycleExecutorException` and `@throws IllegalArgumentException`. Both should
be mirrored here (same applies to the other `executeLifecycle` overloads and
the plan-and-execute variants).
##########
api/maven-api-core/src/main/java/org/apache/maven/api/Session.java:
##########
@@ -217,6 +221,73 @@ default Map<String, String> getEffectiveProperties() {
@Nonnull
Collection<Listener> getListeners();
+ /**
+ * Calculates a lifecycle plan that can be inspected before execution.
+ *
+ * @param project the project for which to calculate the plan
+ * @param tasks lifecycle phases or plugin goals used to calculate the plan
+ * @return the lifecycle planning result
+ * @since 4.1.0
+ */
+ @Nonnull
+ default LifecyclePlanResult planLifecycle(@Nonnull Project project,
@Nonnull List<String> tasks) {
Review Comment:
⚠️ **Missing `@throws` tag** — `planLifecycle` delegates to
`LifecycleExecutor.plan()` which documents `@throws LifecycleExecutorException
if the lifecycle plan cannot be calculated`. The shortcut method should
propagate that declaration:
```suggestion
* @return the lifecycle planning result
* @throws org.apache.maven.api.services.LifecycleExecutorException if
the lifecycle plan cannot be calculated
* @since 4.1.0
```
##########
api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleExecutorException.java:
##########
@@ -0,0 +1,40 @@
+/*
+ * 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.maven.api.services;
+
+import org.apache.maven.api.annotations.Experimental;
+
+/**
+ * Signals that lifecycle planning or execution failed.
+ *
+ * @since 4.1.0
+ */
+@Experimental
+public class LifecycleExecutorException extends MavenException {
+
+ /**
+ * Creates an exception for a lifecycle planning or execution failure.
+ *
+ * @param message the detail message
+ * @param cause the underlying failure
+ */
+ public LifecycleExecutorException(String message, Throwable cause) {
Review Comment:
💡 **Exception constructor coverage** — `LifecycleExecutorException` only
exposes a `(String, Throwable)` constructor. Other v4 `MavenException`
subclasses (e.g. `ProjectBuilderException`, `SettingsBuilderException`) also
provide a message-only `(String)` constructor. Consider adding one for callers
that wrap non-exception error conditions (e.g. plan calculation returning an
empty result with a diagnostic message but no underlying exception).
##########
api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleExecutor.java:
##########
@@ -0,0 +1,91 @@
+/*
+ * 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.maven.api.services;
+
+import java.util.List;
+import java.util.function.Predicate;
+
+import org.apache.maven.api.LifecyclePlan;
+import org.apache.maven.api.MojoExecution;
+import org.apache.maven.api.Project;
+import org.apache.maven.api.Service;
+import org.apache.maven.api.Session;
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Calculates, inspects, and executes Maven lifecycle plans for a single
project.
+ *
+ * @since 4.1.0
+ */
+@Experimental
+public interface LifecycleExecutor extends Service {
Review Comment:
💡 **Naming collision note** — `org.apache.maven.lifecycle.LifecycleExecutor`
already exists as a legacy (compat-layer) interface. Both live in the Maven
classpath and have the same simple name, which will cause import ambiguity for
embedders who access both layers. A brief Javadoc note pointing to the legacy
counterpart (or a `@see` tag) would help orient readers. Example:
```suggestion
/**
* Calculates, inspects, and executes Maven lifecycle plans for a single
project.
*
* <p>Note: this is the Maven API v4 lifecycle executor service. The legacy
* {@code org.apache.maven.lifecycle.LifecycleExecutor} interface serves a
* different role in the compat layer.
*
* @since 4.1.0
*/
@Experimental
public interface LifecycleExecutor extends Service {
```
--
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]
