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 Version 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.ArtifactCoordinateFactory#create(Session, String, String, String, String)
198 */
199 ArtifactCoordinate createArtifactCoordinate(String groupId, String artifactId, String version, String extension);
200
201 /**
202 * Creates a coordinate out of string that is formatted like:
203 * {@code <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>}
204 * <p>
205 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
206 *
207 * @param coordString the string having "standard" coordinate.
208 * @return an {@code ArtifactCoordinate}, never {@code null}
209 * @see org.apache.maven.api.services.ArtifactCoordinateFactory#create(Session, String)
210 */
211 ArtifactCoordinate createArtifactCoordinate(String coordString);
212
213 /**
214 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
215 *
216 * @see org.apache.maven.api.services.ArtifactCoordinateFactory#create(Session, String, String, String, String, String, String)
217 */
218 ArtifactCoordinate createArtifactCoordinate(
219 String groupId, String artifactId, String version, String classifier, String extension, String type);
220
221 /**
222 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
223 *
224 * @see org.apache.maven.api.services.ArtifactCoordinateFactory#create(Session, String, String, String, String, String, String)
225 */
226 ArtifactCoordinate createArtifactCoordinate(Artifact artifact);
227
228 /**
229 * Shortcut for {@code getService(DependencyFactory.class).create(...)}.
230 *
231 * @see DependencyCoordinateFactory#create(Session, ArtifactCoordinate)
232 */
233 @Nonnull
234 DependencyCoordinate createDependencyCoordinate(@Nonnull ArtifactCoordinate coordinate);
235
236 /**
237 * Shortcut for {@code getService(DependencyFactory.class).create(...)}.
238 *
239 * @see DependencyCoordinateFactory#create(Session, Dependency)
240 */
241 @Nonnull
242 DependencyCoordinate createDependencyCoordinate(@Nonnull Dependency dependency);
243
244 /**
245 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
246 *
247 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
248 */
249 Artifact createArtifact(String groupId, String artifactId, String version, String extension);
250
251 /**
252 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
253 *
254 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
255 */
256 Artifact createArtifact(
257 String groupId, String artifactId, String version, String classifier, String extension, String type);
258
259 /**
260 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
261 *
262 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
263 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
264 */
265 Map.Entry<Artifact, Path> resolveArtifact(ArtifactCoordinate coordinate);
266
267 /**
268 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
269 *
270 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
271 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
272 */
273 Map<Artifact, Path> resolveArtifacts(ArtifactCoordinate... coordinates);
274
275 /**
276 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
277 *
278 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
279 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
280 */
281 Map<Artifact, Path> resolveArtifacts(Collection<? extends ArtifactCoordinate> coordinates);
282
283 /**
284 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
285 *
286 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
287 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
288 */
289 Map.Entry<Artifact, Path> resolveArtifact(Artifact artifact);
290
291 /**
292 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
293 *
294 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
295 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
296 */
297 Map<Artifact, Path> resolveArtifacts(Artifact... artifacts);
298
299 /**
300 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}.
301 *
302 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
303 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
304 */
305 void installArtifacts(Artifact... artifacts);
306
307 /**
308 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}.
309 *
310 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
311 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
312 */
313 void installArtifacts(Collection<Artifact> artifacts);
314
315 /**
316 * Shortcut for {@code getService(ArtifactDeployer.class).deploy(...)}.
317 *
318 * @see org.apache.maven.api.services.ArtifactDeployer#deploy(Session, RemoteRepository, Collection)
319 * @throws org.apache.maven.api.services.ArtifactDeployerException if the artifacts deployment failed
320 */
321 void deployArtifact(RemoteRepository repository, Artifact... artifacts);
322
323 /**
324 * Shortcut for {@code getService(ArtifactManager.class).setPath(...)}.
325 *
326 * @see org.apache.maven.api.services.ArtifactManager#setPath(Artifact, Path)
327 */
328 void setArtifactPath(@Nonnull Artifact artifact, @Nonnull Path path);
329
330 /**
331 * Shortcut for {@code getService(ArtifactManager.class).getPath(...)}.
332 *
333 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
334 */
335 @Nonnull
336 Optional<Path> getArtifactPath(@Nonnull Artifact artifact);
337
338 /**
339 * Gets the relative path for a locally installed artifact. Note that the artifact need not actually exist yet at
340 * the returned location, the path merely indicates where the artifact would eventually be stored.
341 * <p>
342 * Shortcut for {@code getService(LocalArtifactManager.class).getPathForLocalArtitact(...)}.
343 *
344 * @see org.apache.maven.api.services.LocalRepositoryManager#getPathForLocalArtifact(Session, LocalRepository, Artifact)
345 */
346 Path getPathForLocalArtifact(@Nonnull Artifact artifact);
347
348 /**
349 * Gets the relative path for an artifact cached from a remote repository.
350 * Note that the artifact need not actually exist yet at the returned location,
351 * the path merely indicates where the artifact would eventually be stored.
352 * <p>
353 * Shortcut for {@code getService(LocalArtifactManager.class).getPathForRemoteArtifact(...)}.
354 *
355 * @see org.apache.maven.api.services.LocalRepositoryManager#getPathForRemoteArtifact(Session, LocalRepository, RemoteRepository, Artifact)
356 */
357 @Nonnull
358 Path getPathForRemoteArtifact(@Nonnull RemoteRepository remote, @Nonnull Artifact artifact);
359
360 /**
361 * Checks whether a given artifact version is considered a {@code SNAPSHOT} or not.
362 * <p>
363 * Shortcut for {@code getService(ArtifactManager.class).isSnapshot(...)}.
364 *
365 * @see org.apache.maven.api.services.VersionParser#isSnapshot(String)
366 */
367 boolean isVersionSnapshot(@Nonnull String version);
368
369 /**
370 * Shortcut for {@code getService(DependencyCollector.class).collect(...)}
371 *
372 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Artifact)
373 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
374 */
375 @Nonnull
376 Node collectDependencies(@Nonnull Artifact artifact);
377
378 /**
379 * Shortcut for {@code getService(DependencyCollector.class).collect(...)}
380 *
381 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Project)
382 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
383 */
384 @Nonnull
385 Node collectDependencies(@Nonnull Project project);
386
387 /**
388 * Collects the transitive dependencies of some artifacts and builds a dependency graph. Note that this operation is
389 * only concerned about determining the coordinates of the transitive dependencies and does not actually resolve the
390 * artifact files.
391 * <p>
392 * Shortcut for {@code getService(DependencyCollector.class).resolve(...)}
393 *
394 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, DependencyCoordinate)
395 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
396 */
397 @Nonnull
398 Node collectDependencies(@Nonnull DependencyCoordinate dependency);
399
400 /**
401 * Shortcut for {@code getService(DependencyResolver.class).flatten(...)}.
402 *
403 * @see org.apache.maven.api.services.DependencyResolver#flatten(Session, Node, ResolutionScope)
404 * @throws org.apache.maven.api.services.DependencyResolverException if the dependency flattening failed
405 */
406 @Nonnull
407 List<Node> flattenDependencies(@Nonnull Node node, @Nonnull ResolutionScope scope);
408
409 @Nonnull
410 List<Path> resolveDependencies(@Nonnull DependencyCoordinate dependencyCoordinate);
411
412 @Nonnull
413 List<Path> resolveDependencies(@Nonnull List<DependencyCoordinate> dependencyCoordinates);
414
415 @Nonnull
416 List<Path> resolveDependencies(@Nonnull Project project, @Nonnull ResolutionScope scope);
417
418 /**
419 * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT"
420 * to "1.0-20090208.132618-23" or "RELEASE"/"LATEST" to "2.0".
421 * <p>
422 * Shortcut for {@code getService(VersionResolver.class).resolve(...)}
423 *
424 * @see org.apache.maven.api.services.VersionResolver#resolve(Session, ArtifactCoordinate) (String)
425 * @throws org.apache.maven.api.services.VersionResolverException if the resolution failed
426 */
427 @Nonnull
428 Version resolveVersion(@Nonnull ArtifactCoordinate artifact);
429
430 /**
431 * Expands a version range to a list of matching versions, in ascending order.
432 * For example, resolves "[3.8,4.0)" to "3.8", "3.8.1", "3.8.2".
433 * The returned list of versions is only dependent on the configured repositories and their contents.
434 * The supplied request may also refer to a single concrete version rather than a version range.
435 * In this case though, the result contains simply the (parsed) input version, regardless of the
436 * repositories and their contents.
437 *
438 * @return a list of resolved {@code Version}s.
439 * @see org.apache.maven.api.services.VersionRangeResolver#resolve(Session, ArtifactCoordinate) (String)
440 * @throws org.apache.maven.api.services.VersionRangeResolverException if the resolution failed
441 */
442 @Nonnull
443 List<Version> resolveVersionRange(@Nonnull ArtifactCoordinate artifact);
444
445 /**
446 * Parses the specified version string, for example "1.0".
447 * <p>
448 * Shortcut for {@code getService(VersionParser.class).parseVersion(...)}.
449 *
450 * @see org.apache.maven.api.services.VersionParser#parseVersion(String)
451 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
452 */
453 @Nonnull
454 Version parseVersion(@Nonnull String version);
455
456 /**
457 * Parses the specified version range specification, for example "[1.0,2.0)".
458 * <p>
459 * Shortcut for {@code getService(VersionParser.class).parseVersionRange(...)}.
460 *
461 * @see org.apache.maven.api.services.VersionParser#parseVersionRange(String)
462 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
463 */
464 @Nonnull
465 VersionRange parseVersionRange(@Nonnull String versionRange);
466 }