gnodet-bot commented on code in PR #14066: URL: https://github.com/apache/maven/pull/14066#discussion_r4619508819
########## api/maven-api-log/pom.xml: ########## @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <modelVersion>4.0.0</modelVersion> + + <parent> + <groupId>org.apache.maven</groupId> + <artifactId>maven-api</artifactId> + <version>4.0.0-SNAPSHOT</version> + </parent> + + <artifactId>maven-api-log</artifactId> + <name>Maven 4 API :: Logging</name> + <description>Maven 4 API - Unified Logging API (Logger, LogEventBuilder, LogLevel).</description> + + <properties> + <javaModuleName>org.apache.maven.api.logging</javaModuleName> Review Comment: ⚠️ **Still missing: `module-info.java` for `maven-api-log`** (must-fix) The module name `org.apache.maven.api.logging` is declared here, but no `module-info.java` exists in the diff. All 11 sibling `maven-api-*` modules have one. Without it, the JPMS module system cannot enforce encapsulation or dependencies. Additionally, `maven-api-core` now depends on this module but its `module-info.java` has no `requires transitive org.apache.maven.api.logging` directive — downstream modules importing `org.apache.maven.api.logging.*` via `maven-api-core` will fail at compile time under JPMS. Required additions: ```java // api/maven-api-log/src/main/java/module-info.java module org.apache.maven.api.logging { exports org.apache.maven.api.logging; } ``` And in `maven-api-core/src/main/java/module-info.java`: ```java requires transitive org.apache.maven.api.logging; ``` ########## api/maven-api-core/src/main/java/org/apache/maven/api/Node.java: ########## @@ -40,40 +40,101 @@ @Provider public interface Node { + /** + * Returns the artifact for this node, or {@code null} for the root node. + * + * @return the artifact, or {@code null} + * @since 4.0.0 + */ + @Nullable + default Artifact artifact() { Review Comment: ⚠️ **Still open: `@Nonnull` delegating to `@Nullable` getter** (must-fix) `artifact()` is annotated `@Nonnull` but delegates unconditionally to `getArtifact()`, which is `@Nullable`. The existing Javadoc on `getArtifact()` says "artifact for this node" — the root node of a dependency tree has no artifact (`getArtifact()` returns `null`). Callers that rely on `@Nonnull` will get a `NullPointerException` without warning. Same problem on `dependency()` → `getDependency()` (line 66–69). The noun-style methods for `Node` must carry `@Nullable` to match the getter contract, or the implementations must throw `NoSuchElementException` with a clear message rather than propagating `null`: ```suggestion @Nullable default Artifact artifact() { return getArtifact(); } ``` ########## api/maven-api-core/src/main/java/org/apache/maven/api/VersionConstraint.java: ########## @@ -37,20 +37,50 @@ */ @Experimental public interface VersionConstraint { + /** + * Returns the range of this constraint, or {@code null} if the constraint is a recommended version. + * <p> + * Note: exactly one of {@link #versionRange()} or {@link #recommendedVersion()} is non-{@code null}. + * + * @return the version range, or {@code null} + * @since 4.0.0 + */ Review Comment: ⚠️ **Still open: `@Nonnull` delegating to `@Nullable` getter** (must-fix) `versionRange()` is `@Nonnull` but delegates to `@Nullable getVersionRange()`. The existing Javadoc on the getter says "or `null` if none" — a constraint that specifies a recommended version (e.g. `1.2.3`) has no version range; `getVersionRange()` legitimately returns `null`. Same applies to `recommendedVersion()` → `getRecommendedVersion()` at line 65. These noun-style accessors must be `@Nullable`: ```suggestion @Nullable default VersionRange versionRange() { return getVersionRange(); } ``` ########## api/maven-api-core/src/main/java/org/apache/maven/api/VersionRange.java: ########## @@ -44,16 +44,42 @@ public interface VersionRange { */ boolean contains(@Nonnull Version version); + /** + * Returns the upper boundary of this range, or {@code null} for an unbounded range (e.g. {@code [1.0,)}). + * + * @return the upper boundary, or {@code null} + * @since 4.0.0 + */ + @Nullable + default Boundary upperBoundary() { Review Comment: ⚠️ **Still open: `@Nonnull` delegating to `@Nullable` getter** (must-fix) `upperBoundary()` is `@Nonnull` but delegates to `@Nullable getUpperBoundary()`. An unbounded range like `[1.0,)` has no upper boundary — `getUpperBoundary()` returns `null` by design. Same for `lowerBoundary()` at line 70. ```suggestion @Nullable default Boundary upperBoundary() { return getUpperBoundary(); } ``` ########## api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java: ########## @@ -29,9 +29,39 @@ */ @Experimental public interface Exclusion { + /** + * Returns the groupId for this exclusion, or {@code null} if unset. + * + * @return the groupId, or {@code null} + * @since 4.0.0 + */ @Nullable + default String groupId() { + return getGroupId(); + } + Review Comment: ⚠️ **Still open: Dangling `@Nullable` annotation** (must-fix) The bare `@Nullable` on line 33 (preceding the new Javadoc block) attaches to `groupId()` in Java's grammar — not to `getGroupId()`. This creates a `@Nullable @Nonnull` contradiction on the same method, which IDEs and annotation processors will flag as an error. The same issue applies to `@Nullable` before `artifactId()`. The `@Nullable` annotations belong on `getGroupId()` and `getArtifactId()` (the deprecated getters), not before the new default methods. Move them: ```suggestion @Nonnull default String groupId() { return getGroupId(); } /** * @deprecated Use {@link #groupId()} instead. */ @Nullable @Deprecated(since = "4.0.0", forRemoval = true) String getGroupId(); ``` ########## api/maven-api-core/src/main/java/org/apache/maven/api/Session.java: ########## @@ -128,7 +128,19 @@ default Map<String, String> getEffectiveProperties() { * Returns the degree of concurrency for the build. * * @return the degree of concurrency + * @since 4.0.0 Review Comment: 📝 `getDegreeOfConcurrency()` has an empty `@deprecated` tag with no replacement. There is no corresponding `degreeOfConcurrency()` noun-style method in the diff. Either: - Add `default int degreeOfConcurrency()` and point the `@deprecated` tag to it, or - Explain in the `@deprecated` tag why the method is removed with no replacement (e.g. "No longer part of the public API — use the build system configuration directly.") An empty `@deprecated` tag gives callers no migration path. ```suggestion * @deprecated No replacement; degree of concurrency is an internal build system concern. ``` -- 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]
