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 /**
105 * @deprecated use {@link #getRootDirectory()} instead
106 */
107 @Nonnull
108 @Deprecated
109 Path getMultiModuleProjectDirectory();
110
111 /**
112 * @deprecated use {@link #getTopDirectory()} instead
113 */
114 @Deprecated
115 @Nonnull
116 Path getExecutionRootDirectory();
117
118 @Nonnull
119 List<Project> getProjects();
120
121 /**
122 * Returns the plugin context for mojo being executed and the specified
123 * {@link Project}, never returns {@code null} as if context not present, creates it.
124 *
125 * <strong>Implementation note:</strong> while this method return type is {@link Map}, the
126 * returned map instance implements {@link java.util.concurrent.ConcurrentMap} as well.
127 *
128 * @throws org.apache.maven.api.services.MavenException if not called from the within a mojo execution
129 */
130 @Nonnull
131 Map<String, Object> getPluginContext(@Nonnull Project project);
132
133 /**
134 * Retrieves the service for the interface
135 *
136 * @throws NoSuchElementException if the service could not be found
137 */
138 @Nonnull
139 <T extends Service> T getService(@Nonnull Class<T> clazz);
140
141 /**
142 * Creates a derived session using the given local repository.
143 *
144 * @param localRepository the new local repository
145 * @return the derived session
146 * @throws NullPointerException if {@code localRepository} is null
147 */
148 @Nonnull
149 Session withLocalRepository(@Nonnull LocalRepository localRepository);
150
151 /**
152 * Creates a derived session using the given remote repositories.
153 *
154 * @param repositories the new list of remote repositories
155 * @return the derived session
156 * @throws NullPointerException if {@code repositories} is null
157 */
158 @Nonnull
159 Session withRemoteRepositories(@Nonnull List<RemoteRepository> repositories);
160
161 /**
162 * Register the given listener which will receive all events.
163 *
164 * @param listener the listener to register
165 * @throws NullPointerException if {@code listener} is null
166 */
167 void registerListener(@Nonnull Listener listener);
168
169 /**
170 * Unregisters a previously registered listener.
171 *
172 * @param listener the listener to unregister
173 * @throws NullPointerException if {@code listener} is null
174 */
175 void unregisterListener(@Nonnull Listener listener);
176
177 /**
178 * Returns the list of registered listeners.
179 *
180 * @return an immutable collection of listeners, never {@code null}
181 */
182 @Nonnull
183 Collection<Listener> getListeners();
184
185 /**
186 * Shortcut for <code>getService(RepositoryFactory.class).createLocal(...)</code>
187 * @see org.apache.maven.api.services.RepositoryFactory#createLocal(Path)
188 */
189 LocalRepository createLocalRepository(Path path);
190
191 /**
192 * Shortcut for <code>getService(RepositoryFactory.class).createRemote(...)</code>
193 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(String, String)
194 */
195 @Nonnull
196 RemoteRepository createRemoteRepository(@Nonnull String id, @Nonnull String url);
197
198 /**
199 * Shortcut for <code>getService(RepositoryFactory.class).createRemote(...)</code>
200 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(Repository)
201 */
202 @Nonnull
203 RemoteRepository createRemoteRepository(@Nonnull Repository repository);
204
205 /**
206 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
207 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
208 */
209 ArtifactCoordinate createArtifactCoordinate(String groupId, String artifactId, String version, String extension);
210
211 /**
212 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
213 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
214 */
215 ArtifactCoordinate createArtifactCoordinate(
216 String groupId, String artifactId, String version, String classifier, String extension, String type);
217
218 /**
219 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
220 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
221 */
222 ArtifactCoordinate createArtifactCoordinate(Artifact artifact);
223
224 /**
225 * Shortcut for <code>getService(DependencyFactory.class).create(...)</code>
226 * @see DependencyCoordinateFactory#create(Session, ArtifactCoordinate)
227 */
228 @Nonnull
229 DependencyCoordinate createDependencyCoordinate(@Nonnull ArtifactCoordinate coordinate);
230
231 /**
232 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
233 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
234 */
235 Artifact createArtifact(String groupId, String artifactId, String version, String extension);
236
237 /**
238 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
239 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
240 */
241 Artifact createArtifact(
242 String groupId, String artifactId, String version, String classifier, String extension, String type);
243
244 /**
245 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
246 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
247 *
248 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
249 */
250 Artifact resolveArtifact(ArtifactCoordinate coordinate);
251
252 /**
253 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
254 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
255 *
256 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
257 */
258 Collection<Artifact> resolveArtifacts(ArtifactCoordinate... coordinates);
259
260 /**
261 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
262 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
263 *
264 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
265 */
266 Collection<Artifact> resolveArtifacts(Collection<? extends ArtifactCoordinate> coordinates);
267
268 /**
269 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
270 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
271 *
272 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
273 */
274 Artifact resolveArtifact(Artifact artifact);
275
276 /**
277 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
278 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
279 *
280 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
281 */
282 Collection<Artifact> resolveArtifacts(Artifact... artifacts);
283
284 /**
285 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}
286 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
287 *
288 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
289 */
290 void installArtifacts(Artifact... artifacts);
291
292 /**
293 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}
294 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
295 *
296 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
297 */
298 void installArtifacts(Collection<Artifact> artifacts);
299
300 /**
301 * Shortcut for <code>getService(ArtifactDeployer.class).deploy(...)</code>
302 * @see org.apache.maven.api.services.ArtifactDeployer#deploy(Session, RemoteRepository, Collection)
303 *
304 * @throws org.apache.maven.api.services.ArtifactDeployerException if the artifacts deployment failed
305 */
306 void deployArtifact(RemoteRepository repository, Artifact... artifacts);
307
308 /**
309 * Shortcut for <code>getService(ArtifactManager.class).setPath(...)</code>
310 * @see org.apache.maven.api.services.ArtifactManager#setPath(Artifact, Path)
311 */
312 void setArtifactPath(@Nonnull Artifact artifact, @Nonnull Path path);
313
314 /**
315 * Shortcut for <code>getService(ArtifactManager.class).getPath(...)</code>
316 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
317 */
318 @Nonnull
319 Optional<Path> getArtifactPath(@Nonnull Artifact artifact);
320
321 /**
322 * Shortcut for <code>getService(ArtifactManager.class).isSnapshot(...)</code>
323 * @see org.apache.maven.api.services.VersionParser#isSnapshot(String)
324 */
325 boolean isVersionSnapshot(@Nonnull String version);
326
327 /**
328 * Shortcut for <code>getService(DependencyCollector.class).collect(...)</code>
329 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Artifact)
330 *
331 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
332 */
333 @Nonnull
334 Node collectDependencies(@Nonnull Artifact artifact);
335
336 /**
337 * Shortcut for <code>getService(DependencyCollector.class).collect(...)</code>
338 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Project)
339 *
340 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
341 */
342 @Nonnull
343 Node collectDependencies(@Nonnull Project project);
344
345 /**
346 * Shortcut for <code>getService(DependencyCollector.class).resolve(...)</code>
347 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, DependencyCoordinate)
348 *
349 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
350 */
351 @Nonnull
352 Node collectDependencies(@Nonnull DependencyCoordinate dependency);
353
354 Path getPathForLocalArtifact(@Nonnull Artifact artifact);
355
356 Path getPathForRemoteArtifact(RemoteRepository remote, Artifact artifact);
357
358 /**
359 * Shortcut for <code>getService(VersionParser.class).parseVersion(...)</code>
360 * @see org.apache.maven.api.services.VersionParser#parseVersion(String)
361 *
362 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
363 */
364 @Nonnull
365 Version parseVersion(@Nonnull String version);
366
367 /**
368 * Shortcut for <code>getService(VersionParser.class).parseVersionRange(...)</code>
369 * @see org.apache.maven.api.services.VersionParser#parseVersionRange(String)
370 *
371 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
372 */
373 @Nonnull
374 VersionRange parseVersionRange(@Nonnull String versionRange);
375 }