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;
20
21 import java.nio.file.Path;
22 import java.time.Instant;
23 import java.util.Collection;
24 import java.util.List;
25 import java.util.Map;
26 import java.util.NoSuchElementException;
27 import java.util.Optional;
28
29 import org.apache.maven.api.annotations.Experimental;
30 import org.apache.maven.api.annotations.Nonnull;
31 import org.apache.maven.api.annotations.ThreadSafe;
32 import org.apache.maven.api.model.Repository;
33 import org.apache.maven.api.services.DependencyCoordinateFactory;
34 import org.apache.maven.api.settings.Settings;
35
36 /**
37 * The session to install / deploy / resolve artifacts and dependencies.
38 *
39 * @since 4.0.0
40 */
41 @Experimental
42 @ThreadSafe
43 public interface Session {
44
45 @Nonnull
46 Settings getSettings();
47
48 @Nonnull
49 LocalRepository getLocalRepository();
50
51 @Nonnull
52 List<RemoteRepository> getRemoteRepositories();
53
54 @Nonnull
55 SessionData getData();
56
57 /**
58 * Gets the user properties to use for interpolation. The user properties have been configured directly by the user,
59 * e.g. via the {@code -Dkey=value} parameter on the command line.
60 *
61 * @return the user properties, never {@code null}
62 */
63 @Nonnull
64 Map<String, String> getUserProperties();
65
66 /**
67 * Gets the system properties to use for interpolation. The system properties are collected from the runtime
68 * environment such as {@link System#getProperties()} and environment variables.
69 *
70 * @return the system properties, never {@code null}
71 */
72 @Nonnull
73 Map<String, String> getSystemProperties();
74
75 /**
76 * Returns the current maven version
77 * @return the maven version, never {@code null}
78 */
79 @Nonnull
80 String getMavenVersion();
81
82 int getDegreeOfConcurrency();
83
84 @Nonnull
85 Instant getStartTime();
86
87 /**
88 * Gets the directory of the topmost project being built, usually the current directory or the
89 * directory pointed at by the {@code -f/--file} command line argument.
90 */
91 @Nonnull
92 Path getTopDirectory();
93
94 /**
95 * Gets the root directory of the session, which is the root directory for the top directory project.
96 *
97 * @throws IllegalStateException if the root directory could not be found
98 * @see #getTopDirectory()
99 * @see Project#getRootDirectory()
100 */
101 @Nonnull
102 Path getRootDirectory();
103
104 @Nonnull
105 List<Project> getProjects();
106
107 /**
108 * Returns the plugin context for mojo being executed and the specified
109 * {@link Project}, never returns {@code null} as if context not present, creates it.
110 *
111 * <strong>Implementation note:</strong> while this method return type is {@link Map}, the
112 * returned map instance implements {@link java.util.concurrent.ConcurrentMap} as well.
113 *
114 * @throws org.apache.maven.api.services.MavenException if not called from the within a mojo execution
115 */
116 @Nonnull
117 Map<String, Object> getPluginContext(@Nonnull Project project);
118
119 /**
120 * Retrieves the service for the interface
121 *
122 * @throws NoSuchElementException if the service could not be found
123 */
124 @Nonnull
125 <T extends Service> T getService(@Nonnull Class<T> clazz);
126
127 /**
128 * Creates a derived session using the given local repository.
129 *
130 * @param localRepository the new local repository
131 * @return the derived session
132 * @throws NullPointerException if {@code localRepository} is null
133 */
134 @Nonnull
135 Session withLocalRepository(@Nonnull LocalRepository localRepository);
136
137 /**
138 * Creates a derived session using the given remote repositories.
139 *
140 * @param repositories the new list of remote repositories
141 * @return the derived session
142 * @throws NullPointerException if {@code repositories} is null
143 */
144 @Nonnull
145 Session withRemoteRepositories(@Nonnull List<RemoteRepository> repositories);
146
147 /**
148 * Register the given listener which will receive all events.
149 *
150 * @param listener the listener to register
151 * @throws NullPointerException if {@code listener} is null
152 */
153 void registerListener(@Nonnull Listener listener);
154
155 /**
156 * Unregisters a previously registered listener.
157 *
158 * @param listener the listener to unregister
159 * @throws NullPointerException if {@code listener} is null
160 */
161 void unregisterListener(@Nonnull Listener listener);
162
163 /**
164 * Returns the list of registered listeners.
165 *
166 * @return an immutable collection of listeners, never {@code null}
167 */
168 @Nonnull
169 Collection<Listener> getListeners();
170
171 /**
172 * Shortcut for {@code getService(RepositoryFactory.class).createLocal(...)}.
173 *
174 * @see org.apache.maven.api.services.RepositoryFactory#createLocal(Path)
175 */
176 LocalRepository createLocalRepository(Path path);
177
178 /**
179 * Shortcut for {@code getService(RepositoryFactory.class).createRemote(...)}.
180 *
181 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(String, String)
182 */
183 @Nonnull
184 RemoteRepository createRemoteRepository(@Nonnull String id, @Nonnull String url);
185
186 /**
187 * Shortcut for {@code getService(RepositoryFactory.class).createRemote(...)}.
188 *
189 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(Repository)
190 */
191 @Nonnull
192 RemoteRepository createRemoteRepository(@Nonnull Repository repository);
193
194 /**
195 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
196 *
197 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
198 */
199 ArtifactCoordinate createArtifactCoordinate(String groupId, String artifactId, String version, String extension);
200
201 /**
202 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
203 *
204 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
205 */
206 ArtifactCoordinate createArtifactCoordinate(
207 String groupId, String artifactId, String version, String classifier, String extension, String type);
208
209 /**
210 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
211 *
212 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
213 */
214 ArtifactCoordinate createArtifactCoordinate(Artifact artifact);
215
216 /**
217 * Shortcut for {@code getService(DependencyFactory.class).create(...)}.
218 *
219 * @see DependencyCoordinateFactory#create(Session, ArtifactCoordinate)
220 */
221 @Nonnull
222 DependencyCoordinate createDependencyCoordinate(@Nonnull ArtifactCoordinate coordinate);
223
224 /**
225 * Shortcut for {@code getService(DependencyFactory.class).create(...)}.
226 *
227 * @see DependencyCoordinateFactory#create(Session, Dependency)
228 */
229 @Nonnull
230 DependencyCoordinate createDependencyCoordinate(@Nonnull Dependency dependency);
231
232 /**
233 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
234 *
235 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
236 */
237 Artifact createArtifact(String groupId, String artifactId, String version, String extension);
238
239 /**
240 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
241 *
242 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
243 */
244 Artifact createArtifact(
245 String groupId, String artifactId, String version, String classifier, String extension, String type);
246
247 /**
248 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
249 *
250 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
251 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
252 */
253 Map.Entry<Artifact, Path> resolveArtifact(ArtifactCoordinate coordinate);
254
255 /**
256 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
257 *
258 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
259 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
260 */
261 Map<Artifact, Path> resolveArtifacts(ArtifactCoordinate... coordinates);
262
263 /**
264 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
265 *
266 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
267 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
268 */
269 Map<Artifact, Path> resolveArtifacts(Collection<? extends ArtifactCoordinate> coordinates);
270
271 /**
272 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
273 *
274 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
275 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
276 */
277 Map.Entry<Artifact, Path> resolveArtifact(Artifact artifact);
278
279 /**
280 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
281 *
282 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
283 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
284 */
285 Map<Artifact, Path> resolveArtifacts(Artifact... artifacts);
286
287 /**
288 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}.
289 *
290 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
291 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
292 */
293 void installArtifacts(Artifact... artifacts);
294
295 /**
296 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}.
297 *
298 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
299 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
300 */
301 void installArtifacts(Collection<Artifact> artifacts);
302
303 /**
304 * Shortcut for {@code getService(ArtifactDeployer.class).deploy(...)}.
305 *
306 * @see org.apache.maven.api.services.ArtifactDeployer#deploy(Session, RemoteRepository, Collection)
307 * @throws org.apache.maven.api.services.ArtifactDeployerException if the artifacts deployment failed
308 */
309 void deployArtifact(RemoteRepository repository, Artifact... artifacts);
310
311 /**
312 * Shortcut for {@code getService(ArtifactManager.class).setPath(...)}.
313 *
314 * @see org.apache.maven.api.services.ArtifactManager#setPath(Artifact, Path)
315 */
316 void setArtifactPath(@Nonnull Artifact artifact, @Nonnull Path path);
317
318 /**
319 * Shortcut for {@code getService(ArtifactManager.class).getPath(...)}.
320 *
321 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
322 */
323 @Nonnull
324 Optional<Path> getArtifactPath(@Nonnull Artifact artifact);
325
326 /**
327 * Gets the relative path for a locally installed artifact. Note that the artifact need not actually exist yet at
328 * the returned location, the path merely indicates where the artifact would eventually be stored.
329 * <p>
330 * Shortcut for {@code getService(LocalArtifactManager.class).getPathForLocalArtitact(...)}.
331 *
332 * @see org.apache.maven.api.services.LocalRepositoryManager#getPathForLocalArtifact(Session, LocalRepository, Artifact)
333 */
334 Path getPathForLocalArtifact(@Nonnull Artifact artifact);
335
336 /**
337 * Gets the relative path for an artifact cached from a remote repository.
338 * Note that the artifact need not actually exist yet at the returned location,
339 * the path merely indicates where the artifact would eventually be stored.
340 * <p>
341 * Shortcut for {@code getService(LocalArtifactManager.class).getPathForRemoteArtifact(...)}.
342 *
343 * @see org.apache.maven.api.services.LocalRepositoryManager#getPathForRemoteArtifact(Session, LocalRepository, RemoteRepository, Artifact)
344 */
345 @Nonnull
346 Path getPathForRemoteArtifact(@Nonnull RemoteRepository remote, @Nonnull Artifact artifact);
347
348 /**
349 * Checks whether a given artifact version is considered a {@code SNAPSHOT} or not.
350 * <p>
351 * Shortcut for {@code getService(ArtifactManager.class).isSnapshot(...)}.
352 *
353 * @see org.apache.maven.api.services.VersionParser#isSnapshot(String)
354 */
355 boolean isVersionSnapshot(@Nonnull String version);
356
357 /**
358 * Shortcut for {@code getService(DependencyCollector.class).collect(...)}
359 *
360 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Artifact)
361 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
362 */
363 @Nonnull
364 Node collectDependencies(@Nonnull Artifact artifact);
365
366 /**
367 * Shortcut for {@code getService(DependencyCollector.class).collect(...)}
368 *
369 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Project)
370 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
371 */
372 @Nonnull
373 Node collectDependencies(@Nonnull Project project);
374
375 /**
376 * Collects the transitive dependencies of some artifacts and builds a dependency graph. Note that this operation is
377 * only concerned about determining the coordinates of the transitive dependencies and does not actually resolve the
378 * artifact files.
379 * <p>
380 * Shortcut for {@code getService(DependencyCollector.class).resolve(...)}
381 *
382 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, DependencyCoordinate)
383 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
384 */
385 @Nonnull
386 Node collectDependencies(@Nonnull DependencyCoordinate dependency);
387
388 /**
389 * Shortcut for {@code getService(DependencyResolver.class).flatten(...)}.
390 *
391 * @see org.apache.maven.api.services.DependencyResolver#flatten(Session, Node, ResolutionScope)
392 * @throws org.apache.maven.api.services.DependencyResolverException if the dependency flattening failed
393 */
394 @Nonnull
395 List<Node> flattenDependencies(@Nonnull Node node, @Nonnull ResolutionScope scope);
396
397 @Nonnull
398 List<Path> resolveDependencies(@Nonnull DependencyCoordinate dependencyCoordinate);
399
400 @Nonnull
401 List<Path> resolveDependencies(@Nonnull List<DependencyCoordinate> dependencyCoordinates);
402
403 @Nonnull
404 List<Path> resolveDependencies(@Nonnull Project project, @Nonnull ResolutionScope scope);
405
406 /**
407 * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT"
408 * to "1.0-20090208.132618-23" or "RELEASE"/"LATEST" to "2.0".
409 * <p>
410 * Shortcut for {@code getService(VersionResolver.class).resolve(...)}
411 *
412 * @see org.apache.maven.api.services.VersionResolver#resolve(Session, ArtifactCoordinate) (String)
413 * @throws org.apache.maven.api.services.VersionResolverException if the resolution failed
414 */
415 @Nonnull
416 Version resolveVersion(@Nonnull ArtifactCoordinate artifact);
417
418 /**
419 * Expands a version range to a list of matching versions, in ascending order.
420 * For example, resolves "[3.8,4.0)" to "3.8", "3.8.1", "3.8.2".
421 * The returned list of versions is only dependent on the configured repositories and their contents.
422 * The supplied request may also refer to a single concrete version rather than a version range.
423 * In this case though, the result contains simply the (parsed) input version, regardless of the
424 * repositories and their contents.
425 *
426 * @return a list of resolved {@code Version}s.
427 * @see org.apache.maven.api.services.VersionRangeResolver#resolve(Session, ArtifactCoordinate) (String)
428 * @throws org.apache.maven.api.services.VersionRangeResolverException if the resolution failed
429 */
430 @Nonnull
431 List<Version> resolveVersionRange(@Nonnull ArtifactCoordinate artifact);
432
433 /**
434 * Parses the specified version string, for example "1.0".
435 * <p>
436 * Shortcut for {@code getService(VersionParser.class).parseVersion(...)}.
437 *
438 * @see org.apache.maven.api.services.VersionParser#parseVersion(String)
439 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
440 */
441 @Nonnull
442 Version parseVersion(@Nonnull String version);
443
444 /**
445 * Parses the specified version range specification, for example "[1.0,2.0)".
446 * <p>
447 * Shortcut for {@code getService(VersionParser.class).parseVersionRange(...)}.
448 *
449 * @see org.apache.maven.api.services.VersionParser#parseVersionRange(String)
450 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
451 */
452 @Nonnull
453 VersionRange parseVersionRange(@Nonnull String versionRange);
454 }