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