1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.maven.api.services;
20
21 import java.nio.file.Path;
22
23 import org.apache.maven.api.annotations.Nonnull;
24 import org.apache.maven.api.annotations.Nullable;
25
26 /**
27 * Represents a source for loading Maven Project Object Model (POM) files. This interface
28 * extends the basic {@link Source} interface with specific functionality for handling
29 * Maven POM files and resolving related project POMs.
30 *
31 * <p>The interface provides two types of sources:</p>
32 * <ul>
33 * <li>Build sources: Used for POM files of projects being built by Maven in the filesystem.
34 * These sources support resolving related POMs using the {@link ModelLocator}.</li>
35 * <li>Resolved sources: Used for artifacts that have been resolved by Maven from repositories
36 * (using groupId:artifactId:version coordinates) and downloaded to the local repository.
37 * These sources do not support resolving other sources.</li>
38 * </ul>
39 *
40 * @since 4.0.0
41 * @see Source
42 */
43 public interface ModelSource extends Source {
44
45 /**
46 * Interface for locating POM files within a project structure.
47 * Implementations of this interface provide the ability to find POM files
48 * in various project contexts.
49 *
50 * @since 4.0.0
51 */
52 interface ModelLocator {
53 /**
54 * Attempts to locate an existing POM file at or within the specified project path.
55 *
56 * <p>This method is used to find POM files in various contexts, such as:</p>
57 * <ul>
58 * <li>Directly at the specified path</li>
59 * <li>Within a directory at the specified path</li>
60 * <li>In standard Maven project locations relative to the specified path</li>
61 * </ul>
62 *
63 * @param project the path to search for a POM file
64 * @return the path to the located POM file, or null if no POM can be found
65 * @throws NullPointerException if project is null
66 */
67 @Nullable
68 Path locateExistingPom(@Nonnull Path project);
69 }
70
71 /**
72 * Resolves a relative path to another POM file using the provided model locator.
73 * This method is specifically used to locate POM files for subprojects or related
74 * projects referenced from the current POM.
75 *
76 * <p>The resolution process typically involves:</p>
77 * <ul>
78 * <li>Normalizing the relative path for the current platform</li>
79 * <li>Resolving the path against the current POM's location</li>
80 * <li>Using the model locator to find an existing POM at the resolved location</li>
81 * </ul>
82 *
83 * @param modelLocator the locator to use for finding the related POM file
84 * @param relative the relative path to resolve
85 * @return a new ModelSource for the resolved POM, or null if:
86 * <ul>
87 * <li>This is not a build source</li>
88 * <li>No POM can be found at the resolved location</li>
89 * </ul>
90 * @throws NullPointerException if modelLocator or relative is null
91 */
92 @Nullable
93 ModelSource resolve(@Nonnull ModelLocator modelLocator, @Nonnull String relative);
94 }