1 package org.apache.maven.api;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.nio.file.Path;
23 import java.time.Instant;
24 import java.util.Collection;
25 import java.util.List;
26 import java.util.Map;
27 import java.util.NoSuchElementException;
28 import java.util.Optional;
29
30 import org.apache.maven.api.annotations.Experimental;
31 import org.apache.maven.api.annotations.Nonnull;
32 import org.apache.maven.api.annotations.ThreadSafe;
33 import org.apache.maven.api.model.Repository;
34 import org.apache.maven.api.services.DependencyCoordinateFactory;
35 import org.apache.maven.api.settings.Settings;
36
37 /**
38 * The session to install / deploy / resolve artifacts and dependencies.
39 *
40 * @since 4.0
41 */
42 @Experimental
43 @ThreadSafe
44 public interface Session
45 {
46
47 @Nonnull
48 Settings getSettings();
49
50 @Nonnull
51 LocalRepository getLocalRepository();
52
53 @Nonnull
54 List<RemoteRepository> getRemoteRepositories();
55
56 @Nonnull
57 SessionData getData();
58
59 @Nonnull
60 Map<String, String> getUserProperties();
61
62 @Nonnull
63 Map<String, String> getSystemProperties();
64
65 /**
66 * Returns the current maven version
67 * @return the maven version, never {@code null}.
68 */
69 @Nonnull
70 String getMavenVersion();
71
72 int getDegreeOfConcurrency();
73
74 @Nonnull
75 Instant getStartTime();
76
77 @Nonnull
78 Path getMultiModuleProjectDirectory();
79
80 @Nonnull
81 Path getExecutionRootDirectory();
82
83 @Nonnull
84 List<Project> getProjects();
85
86 /**
87 * Returns the plugin context for mojo being executed and the specified
88 * {@link Project}, never returns {@code null} as if context not present, creates it.
89 *
90 * <strong>Implementation note:</strong> while this method return type is {@link Map}, the returned map instance
91 * implements {@link java.util.concurrent.ConcurrentMap} as well.
92 *
93 * @throws org.apache.maven.api.services.MavenException if not called from the within a mojo execution
94 */
95 @Nonnull
96 Map<String, Object> getPluginContext( @Nonnull Project project );
97
98 /**
99 * Retrieves the service for the interface
100 *
101 * @throws NoSuchElementException if the service could not be found
102 */
103 @Nonnull
104 <T extends Service> T getService( @Nonnull Class<T> clazz );
105
106 /**
107 * Creates a derived session using the given local repository.
108 *
109 * @param localRepository the new local repository
110 * @return the derived session
111 * @throws NullPointerException if {@code localRepository} is null
112 */
113 @Nonnull
114 Session withLocalRepository( @Nonnull LocalRepository localRepository );
115
116 /**
117 * Creates a derived session using the given remote repositories.
118 *
119 * @param repositories the new list of remote repositories
120 * @return the derived session
121 * @throws NullPointerException if {@code repositories} is null
122 */
123 @Nonnull
124 Session withRemoteRepositories( @Nonnull List<RemoteRepository> repositories );
125
126 /**
127 * Register the given listener which will receive all events.
128 *
129 * @param listener the listener to register
130 * @throws NullPointerException if {@code listener} is null
131 */
132 void registerListener( @Nonnull Listener listener );
133
134 /**
135 * Unregisters a previously registered listener.
136 *
137 * @param listener the listener to unregister
138 * @throws NullPointerException if {@code listener} is null
139 */
140 void unregisterListener( @Nonnull Listener listener );
141
142 /**
143 * Returns the list of registered listeners.
144 *
145 * @return an immutable collection of listeners, never {@code null}
146 */
147 @Nonnull
148 Collection<Listener> getListeners();
149
150 /**
151 * Shortcut for <code>getService(RepositoryFactory.class).createLocal(...)</code>
152 * @see org.apache.maven.api.services.RepositoryFactory#createLocal(Path)
153 */
154 LocalRepository createLocalRepository( Path path );
155
156 /**
157 * Shortcut for <code>getService(RepositoryFactory.class).createRemote(...)</code>
158 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(String, String)
159 */
160 @Nonnull
161 RemoteRepository createRemoteRepository( @Nonnull String id, @Nonnull String url );
162
163 /**
164 * Shortcut for <code>getService(RepositoryFactory.class).createRemote(...)</code>
165 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(Repository)
166 */
167 @Nonnull
168 RemoteRepository createRemoteRepository( @Nonnull Repository repository );
169
170 /**
171 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
172 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
173 */
174 ArtifactCoordinate createArtifactCoordinate( String groupId, String artifactId, String version, String extension );
175
176 /**
177 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
178 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
179 */
180 ArtifactCoordinate createArtifactCoordinate( String groupId, String artifactId, String version, String classifier,
181 String extension, String type );
182
183 /**
184 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
185 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
186 */
187 ArtifactCoordinate createArtifactCoordinate( Artifact artifact );
188
189 /**
190 * Shortcut for <code>getService(DependencyFactory.class).create(...)</code>
191 * @see DependencyCoordinateFactory#create(Session, ArtifactCoordinate)
192 */
193 @Nonnull
194 DependencyCoordinate createDependencyCoordinate( @Nonnull ArtifactCoordinate coordinate );
195
196 /**
197 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
198 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
199 */
200 Artifact createArtifact( String groupId, String artifactId, String version, String extension );
201
202 /**
203 * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
204 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
205 */
206 Artifact createArtifact( String groupId, String artifactId, String version, String classifier,
207 String extension, String type );
208
209 /**
210 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
211 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
212 *
213 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
214 */
215 Artifact resolveArtifact( ArtifactCoordinate coordinate );
216
217 /**
218 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
219 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
220 *
221 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
222 */
223 Collection<Artifact> resolveArtifacts( ArtifactCoordinate... coordinates );
224
225 /**
226 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
227 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
228 *
229 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
230 */
231 Collection<Artifact> resolveArtifacts( Collection<? extends ArtifactCoordinate> coordinates );
232
233 /**
234 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
235 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
236 *
237 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
238 */
239 Artifact resolveArtifact( Artifact artifact );
240
241 /**
242 * Shortcut for <code>getService(ArtifactResolver.class).resolve(...)</code>
243 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
244 *
245 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
246 */
247 Collection<Artifact> resolveArtifacts( Artifact... artifacts );
248
249 /**
250 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}
251 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
252 *
253 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
254 */
255 void installArtifacts( Artifact... artifacts );
256
257 /**
258 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}
259 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
260 *
261 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
262 */
263 void installArtifacts( Collection<Artifact> artifacts );
264
265 /**
266 * Shortcut for <code>getService(ArtifactDeployer.class).deploy(...)</code>
267 * @see org.apache.maven.api.services.ArtifactDeployer#deploy(Session, RemoteRepository, Collection)
268 *
269 * @throws org.apache.maven.api.services.ArtifactDeployerException if the artifacts deployment failed
270 */
271 void deployArtifact( RemoteRepository repository, Artifact... artifacts );
272
273 /**
274 * Shortcut for <code>getService(ArtifactManager.class).setPath(...)</code>
275 * @see org.apache.maven.api.services.ArtifactManager#setPath(Artifact, Path)
276 */
277 void setArtifactPath( @Nonnull Artifact artifact, @Nonnull Path path );
278
279 /**
280 * Shortcut for <code>getService(ArtifactManager.class).getPath(...)</code>
281 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
282 */
283 @Nonnull
284 Optional<Path> getArtifactPath( @Nonnull Artifact artifact );
285
286 /**
287 * Shortcut for <code>getService(ArtifactManager.class).isSnapshot(...)</code>
288 * @see org.apache.maven.api.services.VersionParser#isSnapshot(String)
289 */
290 boolean isVersionSnapshot( @Nonnull String version );
291
292 /**
293 * Shortcut for <code>getService(DependencyCollector.class).collect(...)</code>
294 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Artifact)
295 *
296 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
297 */
298 @Nonnull
299 Node collectDependencies( @Nonnull Artifact artifact );
300
301 /**
302 * Shortcut for <code>getService(DependencyCollector.class).collect(...)</code>
303 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Project)
304 *
305 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
306 */
307 @Nonnull
308 Node collectDependencies( @Nonnull Project project );
309
310 /**
311 * Shortcut for <code>getService(DependencyResolver.class).resolve(...)</code>
312 * @see org.apache.maven.api.services.DependencyCollector#collect(Session, DependencyCoordinate)
313 *
314 * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
315 */
316 @Nonnull
317 Node collectDependencies( @Nonnull DependencyCoordinate dependency );
318
319 Path getPathForLocalArtifact( @Nonnull Artifact artifact );
320
321 Path getPathForRemoteArtifact( RemoteRepository remote, Artifact artifact );
322
323 /**
324 * Shortcut for <code>getService(VersionParser.class).parseVersion(...)</code>
325 * @see org.apache.maven.api.services.VersionParser#parseVersion(String)
326 *
327 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
328 */
329 @Nonnull
330 Version parseVersion( @Nonnull String version );
331
332 /**
333 * Shortcut for <code>getService(VersionParser.class).parseVersionRange(...)</code>
334 * @see org.apache.maven.api.services.VersionParser#parseVersionRange(String)
335 *
336 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
337 */
338 @Nonnull
339 VersionRange parseVersionRange( @Nonnull String versionRange );
340 }