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 import org.apache.maven.api.annotations.Experimental;
29 import org.apache.maven.api.annotations.Nonnull;
30 import org.apache.maven.api.annotations.ThreadSafe;
31 import org.apache.maven.api.model.Repository;
32 import org.apache.maven.api.services.DependencyCoordinateFactory;
33 import org.apache.maven.api.settings.Settings;
34
35 /**
36 * The session to install / deploy / resolve artifacts and dependencies.
37 *
38 * @since 4.0
39 */
40 @Experimental
41 @ThreadSafe
42 public interface Session {
43
44 @Nonnull
45 Settings getSettings();
46
47 @Nonnull
48 LocalRepository getLocalRepository();
49
50 @Nonnull
51 List<RemoteRepository> getRemoteRepositories();
52
53 @Nonnull
54 SessionData getData();
55
56 /**
57 * Gets the user properties to use for interpolation. The user properties have been configured directly by the user,
58 * e.g. via the {@code -Dkey=value} parameter on the command line.
59 *
60 * @return the user properties, never {@code null}
61 */
62 @Nonnull
63 Map<String, String> getUserProperties();
64
65 /**
66 * Gets the system properties to use for interpolation. The system properties are collected from the runtime
67 * environment such as {@link System#getProperties()} and environment variables.
68 *
69 * @return the system properties, never {@code null}
70 */
71 @Nonnull
72 Map<String, String> getSystemProperties();
73
74 /**
75 * Returns the current maven version
76 * @return the maven version, never {@code null}
77 */
78 @Nonnull
79 String getMavenVersion();
80
81 int getDegreeOfConcurrency();
82
83 @Nonnull
84 Instant getStartTime();
85
86 @Nonnull
87 Path getMultiModuleProjectDirectory();
88
89 @Nonnull
90 Path getExecutionRootDirectory();
91
92 @Nonnull
93 List<Project> getProjects();
94
95 /**
96 * Returns the plugin context for mojo being executed and the specified
97 * {@link Project}, never returns {@code null} as if context not present, creates it.
98 *
99 * <strong>Implementation note:</strong> while this method return type is {@link Map}, the returned map instance
100 * implements {@link java.util.concurrent.ConcurrentMap} as well.
101 *
102 * @throws org.apache.maven.api.services.MavenException if not called from the within a mojo execution
103 */
104 @Nonnull
105 Map<String, Object> getPluginContext(@Nonnull Project project);
106
107 /**
108 * Retrieves the service for the interface
109 *
110 * @throws NoSuchElementException if the service could not be found
111 */
112 @Nonnull
113 <T extends Service> T getService(@Nonnull Class<T> clazz);
114
115 /**
116 * Creates a derived session using the given local repository.
117 *
118 * @param localRepository the new local repository
119 * @return the derived session
120 * @throws NullPointerException if {@code localRepository} is null
121 */
122 @Nonnull
123 Session withLocalRepository(@Nonnull LocalRepository localRepository);
124
125 /**
126 * Creates a derived session using the given remote repositories.
127 *
128 * @param repositories the new list of remote repositories
129 * @return the derived session
130 * @throws NullPointerException if {@code repositories} is null
131 */
132 @Nonnull
133 Session withRemoteRepositories(@Nonnull List<RemoteRepository> repositories);
134
135 /**
136 * Register the given listener which will receive all events.
137 *
138 * @param listener the listener to register
139 * @throws NullPointerException if {@code listener} is null
140 */
141 void registerListener(@Nonnull Listener listener);
142
143 /**
144 * Unregisters a previously registered listener.
145 *
146 * @param listener the listener to unregister
147 * @throws NullPointerException if {@code listener} is null
148 */
149 void unregisterListener(@Nonnull Listener listener);
150
151 /**
152 * Returns the list of registered listeners.
153 *
154 * @return an immutable collection of listeners, never {@code null}
155 */
156 @Nonnull
157 Collection<Listener> getListeners();
158
159 /**
160 * Shortcut for <code>getService(RepositoryFactory.class).createLocal(...)</code>
161 * @see org.apache.maven.api.services.RepositoryFactory#createLocal(Path)
162 */
163 LocalRepository createLocalRepository(Path path);
164
165 /**
166 * Shortcut for <code>getService(RepositoryFactory.class).createRemote(...)</code>
167 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(String, String)
168 */
169 @Nonnull
170 RemoteRepository createRemoteRepository(@Nonnull String id, @Nonnull String url);
171
172 /**
173 * Shortcut for <code>getService(RepositoryFactory.class).createRemote(...)</code>
174 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(Repository)
175 */
176 @Nonnull
177 RemoteRepository createRemoteRepository(@Nonnull Repository repository);
178
179 /**
180 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
181 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
182 */
183 ArtifactCoordinate createArtifactCoordinate(String groupId, String artifactId, String version, String extension);
184
185 /**
186 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
187 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
188 */
189 ArtifactCoordinate createArtifactCoordinate(
190 String groupId, String artifactId, String version, String classifier, String extension, String type);
191
192 /**
193 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
194 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
195 */
196 ArtifactCoordinate createArtifactCoordinate(Artifact artifact);
197
198 /**
199 * Shortcut for <code>getService(DependencyFactory.class).create(...)</code>
200 * @see DependencyCoordinateFactory#create(Session, ArtifactCoordinate)
201 */
202 @Nonnull
203 DependencyCoordinate createDependencyCoordinate(@Nonnull ArtifactCoordinate coordinate);
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 Artifact createArtifact(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 Artifact createArtifact(
216 String groupId, String artifactId, String version, String classifier, String extension, String type);
217
218 /**
219 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
220 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
221 *
222 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
223 */
224 Artifact resolveArtifact(ArtifactCoordinate coordinate);
225
226 /**
227 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
228 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
229 *
230 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
231 */
232 Collection<Artifact> resolveArtifacts(ArtifactCoordinate... coordinates);
233
234 /**
235 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
236 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
237 *
238 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
239 */
240 Collection<Artifact> resolveArtifacts(Collection<? extends ArtifactCoordinate> coordinates);
241
242 /**
243 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
244 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
245 *
246 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
247 */
248 Artifact resolveArtifact(Artifact artifact);
249
250 /**
251 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
252 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
253 *
254 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
255 */
256 Collection<Artifact> resolveArtifacts(Artifact... artifacts);
257
258 /**
259 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}
260 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
261 *
262 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
263 */
264 void installArtifacts(Artifact... artifacts);
265
266 /**
267 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}
268 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
269 *
270 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
271 */
272 void installArtifacts(Collection<Artifact> artifacts);
273
274 /**
275 * Shortcut for <code>getService(ArtifactDeployer.class).deploy(...)</code>
276 * @see org.apache.maven.api.services.ArtifactDeployer#deploy(Session, RemoteRepository, Collection)
277 *
278 * @throws org.apache.maven.api.services.ArtifactDeployerException if the artifacts deployment failed
279 */
280 void deployArtifact(RemoteRepository repository, Artifact... artifacts);
281
282 /**
283 * Shortcut for <code>getService(ArtifactManager.class).setPath(...)</code>
284 * @see org.apache.maven.api.services.ArtifactManager#setPath(Artifact, Path)
285 */
286 void setArtifactPath(@Nonnull Artifact artifact, @Nonnull Path path);
287
288 /**
289 * Shortcut for <code>getService(ArtifactManager.class).getPath(...)</code>
290 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
291 */
292 @Nonnull
293 Optional<Path> getArtifactPath(@Nonnull Artifact artifact);
294
295 /**
296 * Shortcut for <code>getService(ArtifactManager.class).isSnapshot(...)</code>
297 * @see org.apache.maven.api.services.VersionParser#isSnapshot(String)
298 */
299 boolean isVersionSnapshot(@Nonnull String version);
300
301 /**
302 * Shortcut for <code>getService(DependencyCollector.class).collect(...)</code>
303 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Artifact)
304 *
305 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
306 */
307 @Nonnull
308 Node collectDependencies(@Nonnull Artifact artifact);
309
310 /**
311 * Shortcut for <code>getService(DependencyCollector.class).collect(...)</code>
312 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Project)
313 *
314 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
315 */
316 @Nonnull
317 Node collectDependencies(@Nonnull Project project);
318
319 /**
320 * Shortcut for <code>getService(DependencyResolver.class).resolve(...)</code>
321 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, DependencyCoordinate)
322 *
323 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
324 */
325 @Nonnull
326 Node collectDependencies(@Nonnull DependencyCoordinate dependency);
327
328 Path getPathForLocalArtifact(@Nonnull Artifact artifact);
329
330 Path getPathForRemoteArtifact(RemoteRepository remote, Artifact artifact);
331
332 /**
333 * Shortcut for <code>getService(VersionParser.class).parseVersion(...)</code>
334 * @see org.apache.maven.api.services.VersionParser#parseVersion(String)
335 *
336 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
337 */
338 @Nonnull
339 Version parseVersion(@Nonnull String version);
340
341 /**
342 * Shortcut for <code>getService(VersionParser.class).parseVersionRange(...)</code>
343 * @see org.apache.maven.api.services.VersionParser#parseVersionRange(String)
344 *
345 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
346 */
347 @Nonnull
348 VersionRange parseVersionRange(@Nonnull String versionRange);
349 }