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.model.resolution;
20
21 import java.util.concurrent.atomic.AtomicReference;
22
23 import org.apache.maven.api.model.Dependency;
24 import org.apache.maven.api.model.Parent;
25 import org.apache.maven.api.model.Repository;
26 import org.apache.maven.model.building.ModelSource;
27
28 /**
29 * Resolves a POM from its coordinates. During the build process, the
30 * {@link org.apache.maven.model.building.ModelBuilder} will add any relevant repositories to the model resolver. In
31 * other words, the model resolver is stateful and should not be reused across multiple model building requests.
32 *
33 * @author Benjamin Bentmann
34 */
35 public interface ModelResolver {
36
37 /**
38 * Tries to resolve the POM for the specified coordinates.
39 *
40 * @param groupId The group identifier of the POM, must not be {@code null}.
41 * @param artifactId The artifact identifier of the POM, must not be {@code null}.
42 * @param version The version of the POM, must not be {@code null}.
43 * @return The source of the requested POM, never {@code null}.
44 * @throws UnresolvableModelException If the POM could not be resolved from any configured repository.
45 */
46 ModelSource resolveModel(String groupId, String artifactId, String version) throws UnresolvableModelException;
47
48 /**
49 * Tries to resolve the POM for the specified parent coordinates possibly updating {@code parent}.
50 * <p>
51 * Unlike the {@link #resolveModel(java.lang.String, java.lang.String, java.lang.String)} method, this method
52 * supports version ranges and updates the given {@code parent} instance to match the returned {@code ModelSource}.
53 * If {@code parent} declares a version range, the version corresponding to the returned {@code ModelSource} will
54 * be set on the given {@code parent}.
55 * </p>
56 *
57 * @param parent The parent coordinates to resolve, must not be {@code null}.
58 *
59 * @return The source of the requested POM, never {@code null}.
60 *
61 * @throws UnresolvableModelException If the POM could not be resolved from any configured repository.
62 * @since 3.2.2
63 *
64 * @see Parent#clone()
65 */
66 ModelSource resolveModel(org.apache.maven.model.Parent parent) throws UnresolvableModelException;
67
68 /**
69 * Tries to resolve the POM for the specified dependency coordinates possibly updating {@code dependency}.
70 * <p>
71 * Unlike the {@link #resolveModel(java.lang.String, java.lang.String, java.lang.String)} method, this method
72 * supports version ranges and updates the given {@code dependency} instance to match the returned
73 * {@code ModelSource}. If {@code dependency} declares a version range, the version corresponding to the returned
74 * {@code ModelSource} will be set on the given {@code dependency}.
75 * </p>
76 *
77 * @param dependency The dependency coordinates to resolve, must not be {@code null}.
78 *
79 * @return The source of the requested POM, never {@code null}.
80 *
81 * @throws UnresolvableModelException If the POM could not be resolved from any configured repository.
82 * @since 3.5.0
83 *
84 * @see Dependency#clone()
85 */
86 ModelSource resolveModel(org.apache.maven.model.Dependency dependency) throws UnresolvableModelException;
87
88 /**
89 * Adds a repository to use for subsequent resolution requests. The order in which repositories are added matters,
90 * repositories that were added first should also be searched first. When multiple repositories with the same
91 * identifier are added, only the first repository being added will be used.
92 *
93 * @param repository The repository to add to the internal search chain, must not be {@code null}.
94 * @throws InvalidRepositoryException If the repository could not be added (e.g. due to invalid URL or layout).
95 */
96 void addRepository(org.apache.maven.model.Repository repository) throws InvalidRepositoryException;
97
98 /**
99 * Adds a repository to use for subsequent resolution requests. The order in which repositories are added matters,
100 * repositories that were added first should also be searched first. When multiple repositories with the same
101 * identifier are added, then the value of the replace argument determines the behaviour.
102 *
103 * If replace is false then any existing repository with the same Id will remain in use. If replace
104 * is true the new repository replaces the original.
105 *
106 * @param repository The repository to add to the internal search chain, must not be {@code null}.
107 * @throws InvalidRepositoryException If the repository could not be added (e.g. due to invalid URL or layout).
108 */
109 void addRepository(org.apache.maven.model.Repository repository, boolean replace) throws InvalidRepositoryException;
110
111 /**
112 * Clones this resolver for usage in a forked resolution process. In general, implementors need not provide a deep
113 * clone. The only requirement is that invocations of {@link #addRepository(Repository)} on the clone do not affect
114 * the state of the original resolver and vice versa.
115 *
116 * @return The cloned resolver, never {@code null}.
117 */
118 ModelResolver newCopy();
119
120 default ModelSource resolveModel(Parent parent, AtomicReference<Parent> modified)
121 throws UnresolvableModelException {
122 org.apache.maven.model.Parent p = new org.apache.maven.model.Parent(parent);
123 ModelSource result = resolveModel(p);
124 if (p.getDelegate() != parent) {
125 modified.set(p.getDelegate());
126 }
127 return result;
128 }
129
130 default ModelSource resolveModel(Dependency dependency, AtomicReference<Dependency> modified)
131 throws UnresolvableModelException {
132 org.apache.maven.model.Dependency d = new org.apache.maven.model.Dependency(dependency);
133 ModelSource result = resolveModel(d);
134 if (d.getDelegate() != dependency) {
135 modified.set(d.getDelegate());
136 }
137 return result;
138 }
139
140 default void addRepository(Repository repository) throws InvalidRepositoryException {
141 addRepository(new org.apache.maven.model.Repository(repository));
142 }
143
144 default void addRepository(Repository repository, boolean replace) throws InvalidRepositoryException {
145 addRepository(new org.apache.maven.model.Repository(repository), replace);
146 }
147 }