gnodet-bot commented on code in PR #13445:
URL: https://github.com/apache/maven/pull/13445#discussion_r4249914647
##########
api/maven-api-core/src/main/java/org/apache/maven/api/services/RepositoryFactory.java:
##########
@@ -37,15 +37,64 @@
@Experimental
public interface RepositoryFactory extends Service {
+ /**
+ * Creates a {@link LocalRepository} backed by the given filesystem path.
+ * The path will be converted to an absolute path.
+ *
+ * @param path the filesystem path to the local repository, must not be
{@code null}
+ * @return a new local repository instance, never {@code null}
+ */
@Nonnull
LocalRepository createLocal(@Nonnull Path path);
+ /**
+ * Creates a {@link RemoteRepository} with the given identifier and URL.
+ * The repository will use the standard default layout and default release
+ * and snapshot policies.
+ *
+ * @param id the identifier of the remote repository, must not be {@code
null}
+ * @param url the URL of the remote repository, must not be {@code null}
+ * @return a new remote repository instance, never {@code null}
+ */
@Nonnull
RemoteRepository createRemote(@Nonnull String id, @Nonnull String url);
+ /**
+ * Creates a {@link RemoteRepository} from the given POM model repository
definition.
+ * <p>
+ * The returned repository preserves the identifier, layout, and URL from
the model,
+ * and translates its release and snapshot policies (including enabled
state, update
+ * policy, and checksum policy).
+ *
Review Comment:
⚠️ **Nit:** The `@throws IllegalArgumentException` claim isn't clearly
backed by the contract or the known implementation.
`DefaultRepositoryFactory.createRemote(Repository)` performs no explicit
validation and delegates straight to the builder. Either remove this `@throws`
tag, or add actual precondition validation (e.g. a null/empty-URL check) so the
contract is meaningful.
##########
api/maven-api-core/src/main/java/org/apache/maven/api/services/RepositoryFactory.java:
##########
@@ -37,15 +37,64 @@
@Experimental
public interface RepositoryFactory extends Service {
+ /**
+ * Creates a {@link LocalRepository} backed by the given filesystem path.
+ * The path will be converted to an absolute path.
+ *
+ * @param path the filesystem path to the local repository, must not be
{@code null}
+ * @return a new local repository instance, never {@code null}
+ */
@Nonnull
LocalRepository createLocal(@Nonnull Path path);
+ /**
+ * Creates a {@link RemoteRepository} with the given identifier and URL.
+ * The repository will use the standard default layout and default release
+ * and snapshot policies.
+ *
+ * @param id the identifier of the remote repository, must not be {@code
null}
+ * @param url the URL of the remote repository, must not be {@code null}
+ * @return a new remote repository instance, never {@code null}
+ */
@Nonnull
RemoteRepository createRemote(@Nonnull String id, @Nonnull String url);
+ /**
+ * Creates a {@link RemoteRepository} from the given POM model repository
definition.
+ * <p>
+ * The returned repository preserves the identifier, layout, and URL from
the model,
+ * and translates its release and snapshot policies (including enabled
state, update
+ * policy, and checksum policy).
+ *
+ * @param repository the model repository to convert, must not be {@code
null}
+ * @return a new remote repository instance, never {@code null}
+ * @throws IllegalArgumentException if the model repository is invalid
+ */
@Nonnull
RemoteRepository createRemote(@Nonnull Repository repository);
+ /**
+ * Aggregates two lists of remote repositories into a single list by
merging
+ * definitions and resolving duplicates.
+ * <p>
+ * Repositories in the {@code dominant} list take precedence over
repositories
+ * in the {@code recessive} list with matching identifiers. The aggregated
list
+ * retains the order of dominant repositories, followed by non-duplicate
recessive
+ * repositories.
+ * <p>
+ * When {@code processRecessive} is {@code true}, recessive repositories
are treated
+ * as raw definitions and are subjected to mirror selection, proxy
selection, and
Review Comment:
💡 **Suggestion:** This paragraph describes Resolver internals (mirror
selection, proxy selection, authentication) rather than the API contract. These
details are implementation-specific and may not hold for alternative
implementations. Consider rephrasing in contract terms — e.g. _"When
`processRecessive` is `true`, recessive repositories are treated as
raw/unconfigured definitions and will have session-level settings applied; when
`false`, they are assumed already configured and merged as-is."_
--
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]
