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.eclipse.aether;
20
21 import java.io.Closeable;
22 import java.nio.file.Path;
23 import java.util.Collection;
24 import java.util.Map;
25 import java.util.function.Supplier;
26
27 import org.eclipse.aether.artifact.ArtifactTypeRegistry;
28 import org.eclipse.aether.collection.DependencyCollectionChecker;
29 import org.eclipse.aether.collection.DependencyGraphTransformer;
30 import org.eclipse.aether.collection.DependencyManager;
31 import org.eclipse.aether.collection.DependencySelector;
32 import org.eclipse.aether.collection.DependencyTraverser;
33 import org.eclipse.aether.collection.VersionFilter;
34 import org.eclipse.aether.repository.AuthenticationSelector;
35 import org.eclipse.aether.repository.LocalRepository;
36 import org.eclipse.aether.repository.LocalRepositoryManager;
37 import org.eclipse.aether.repository.MirrorSelector;
38 import org.eclipse.aether.repository.ProxySelector;
39 import org.eclipse.aether.repository.RemoteRepository;
40 import org.eclipse.aether.repository.RepositoryPolicy;
41 import org.eclipse.aether.repository.WorkspaceReader;
42 import org.eclipse.aether.resolution.ArtifactDescriptorPolicy;
43 import org.eclipse.aether.resolution.ResolutionErrorPolicy;
44 import org.eclipse.aether.scope.ScopeManager;
45 import org.eclipse.aether.scope.SystemDependencyScope;
46 import org.eclipse.aether.transfer.TransferListener;
47
48 /**
49 * Defines settings and components that control the repository system. Once initialized, the session object itself is
50 * supposed to be immutable and hence can safely be shared across an entire application and any concurrent threads
51 * reading it. Components that wish to tweak some aspects of an existing session should use the copy constructor of
52 * {@link DefaultRepositorySystemSession} and its mutators to derive a custom session.
53 *
54 * @noimplement This interface is not intended to be implemented by clients.
55 * @noextend This interface is not intended to be extended by clients.
56 */
57 public interface RepositorySystemSession {
58
59 /**
60 * Immutable session that is closeable, should be handled as a resource. These session instances can be
61 * created with {@link SessionBuilder}.
62 *
63 * @noimplement This interface is not intended to be implemented by clients.
64 * @noextend This interface is not intended to be extended by clients.
65 *
66 * @since 2.0.0
67 */
68 interface CloseableSession extends RepositorySystemSession, Closeable {
69 /**
70 * Returns the ID of this closeable session instance. Each closeable session has different ID, unique within
71 * repository system they were created with.
72 *
73 * @return The session ID that is never {@code null}.
74 */
75 String sessionId();
76
77 /**
78 * Closes the session. The session should be closed by its creator. A closed session should not be used anymore.
79 * This method may be invoked multiple times, but close will act only once (first time).
80 */
81 @Override
82 void close();
83 }
84
85 /**
86 * Builder for building {@link CloseableSession} instances. Builder instances can be created with
87 * {@link RepositorySystem#createSessionBuilder()} method. Instances are not thread-safe nor immutable.
88 * <p>
89 * Important: if you set a stateful member on builder (for example {@link SessionData} or {@link RepositoryCache}),
90 * the builder will create session instances using same provided stateful members, that may lead to unexpected side
91 * effects. Solution for these cases is to not reuse builder instances, or, keep reconfiguring it, or ultimately
92 * provide suppliers that create new instance per each call.
93 *
94 * @noimplement This interface is not intended to be implemented by clients.
95 * @noextend This interface is not intended to be extended by clients.
96 *
97 * @since 2.0.0
98 */
99 interface SessionBuilder {
100 /**
101 * Controls whether the repository system operates in offline mode and avoids/refuses any access to remote
102 * repositories.
103 *
104 * @param offline {@code true} if the repository system is in offline mode, {@code false} otherwise.
105 * @return This session for chaining, never {@code null}.
106 */
107 SessionBuilder setOffline(boolean offline);
108
109 /**
110 * Controls whether repositories declared in artifact descriptors should be ignored during transitive dependency
111 * collection. If enabled, only the repositories originally provided with the collect request will be considered.
112 *
113 * @param ignoreArtifactDescriptorRepositories {@code true} to ignore additional repositories from artifact
114 * descriptors, {@code false} to merge those with the originally
115 * specified repositories.
116 * @return This session for chaining, never {@code null}.
117 */
118 SessionBuilder setIgnoreArtifactDescriptorRepositories(boolean ignoreArtifactDescriptorRepositories);
119
120 /**
121 * Sets the policy which controls whether resolutions errors from remote repositories should be cached.
122 *
123 * @param resolutionErrorPolicy The resolution error policy for this session, may be {@code null} if resolution
124 * errors should generally not be cached.
125 * @return This session for chaining, never {@code null}.
126 */
127 SessionBuilder setResolutionErrorPolicy(ResolutionErrorPolicy resolutionErrorPolicy);
128
129 /**
130 * Sets the policy which controls how errors related to reading artifact descriptors should be handled.
131 *
132 * @param artifactDescriptorPolicy The descriptor error policy for this session, may be {@code null} if descriptor
133 * errors should generally not be tolerated.
134 * @return This session for chaining, never {@code null}.
135 */
136 SessionBuilder setArtifactDescriptorPolicy(ArtifactDescriptorPolicy artifactDescriptorPolicy);
137
138 /**
139 * Sets the global checksum policy. If set, the global checksum policy overrides the checksum policies of the remote
140 * repositories being used for resolution.
141 *
142 * @param checksumPolicy The global checksum policy, may be {@code null}/empty to apply the per-repository policies.
143 * @return This session for chaining, never {@code null}.
144 * @see RepositoryPolicy#CHECKSUM_POLICY_FAIL
145 * @see RepositoryPolicy#CHECKSUM_POLICY_IGNORE
146 * @see RepositoryPolicy#CHECKSUM_POLICY_WARN
147 */
148 SessionBuilder setChecksumPolicy(String checksumPolicy);
149
150 /**
151 * Sets the global update policy. If set, the global update policy overrides the update policies of the remote
152 * repositories being used for resolution.
153 * <p>
154 * This method is meant for code that does not want to distinguish between artifact and metadata policies.
155 * Note: applications should either use get/set updatePolicy (this method and
156 * {@link RepositorySystemSession#getUpdatePolicy()}) or also distinguish between artifact and
157 * metadata update policies (and use other methods), but <em>should not mix the two!</em>
158 *
159 * @param updatePolicy The global update policy, may be {@code null}/empty to apply the per-repository policies.
160 * @return This session for chaining, never {@code null}.
161 * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
162 * @see RepositoryPolicy#UPDATE_POLICY_DAILY
163 * @see RepositoryPolicy#UPDATE_POLICY_NEVER
164 * @see #setArtifactUpdatePolicy(String)
165 * @see #setMetadataUpdatePolicy(String)
166 */
167 SessionBuilder setUpdatePolicy(String updatePolicy);
168
169 /**
170 * Sets the global artifact update policy. If set, the global update policy overrides the artifact update policies
171 * of the remote repositories being used for resolution.
172 *
173 * @param artifactUpdatePolicy The global update policy, may be {@code null}/empty to apply the per-repository policies.
174 * @return This session for chaining, never {@code null}.
175 * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
176 * @see RepositoryPolicy#UPDATE_POLICY_DAILY
177 * @see RepositoryPolicy#UPDATE_POLICY_NEVER
178 * @since 2.0.0
179 */
180 SessionBuilder setArtifactUpdatePolicy(String artifactUpdatePolicy);
181
182 /**
183 * Sets the global metadata update policy. If set, the global update policy overrides the metadata update policies
184 * of the remote repositories being used for resolution.
185 *
186 * @param metadataUpdatePolicy The global update policy, may be {@code null}/empty to apply the per-repository policies.
187 * @return This session for chaining, never {@code null}.
188 * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
189 * @see RepositoryPolicy#UPDATE_POLICY_DAILY
190 * @see RepositoryPolicy#UPDATE_POLICY_NEVER
191 * @since 2.0.0
192 */
193 SessionBuilder setMetadataUpdatePolicy(String metadataUpdatePolicy);
194
195 /**
196 * Sets the local repository manager used during this session. <em>Note:</em> Eventually, a valid session must have
197 * a local repository manager set.
198 * <p>
199 * The provisioning of {@link org.eclipse.aether.repository.LocalRepositoryManager} for use with this
200 * method introduces chicken and egg situation. Integrators MUST NOT use this method, but instead, hook into
201 * Local Repository Manager Provider by any means they can (ie by using Provider or Sisu Components) and use
202 * custom string and/or priorities instead. This method existence is not meant for "everyday use" (normal
203 * session creation), but for some more advanced use cases. Do not use it, unless you know what are you doing.
204 *
205 * @param localRepositoryManager The local repository manager used during this session, may be {@code null}.
206 * @return This session for chaining, never {@code null}.
207 */
208 SessionBuilder setLocalRepositoryManager(LocalRepositoryManager localRepositoryManager);
209
210 /**
211 * Sets the workspace reader used during this session. If set, the workspace reader will usually be consulted first
212 * to resolve artifacts.
213 *
214 * @param workspaceReader The workspace reader for this session, may be {@code null} if none.
215 * @return This session for chaining, never {@code null}.
216 */
217 SessionBuilder setWorkspaceReader(WorkspaceReader workspaceReader);
218
219 /**
220 * Sets the listener being notified of actions in the repository system.
221 *
222 * @param repositoryListener The repository listener, may be {@code null} if none.
223 * @return This session for chaining, never {@code null}.
224 */
225 SessionBuilder setRepositoryListener(RepositoryListener repositoryListener);
226
227 /**
228 * Sets the listener being notified of uploads/downloads by the repository system.
229 *
230 * @param transferListener The transfer listener, may be {@code null} if none.
231 * @return This session for chaining, never {@code null}.
232 */
233 SessionBuilder setTransferListener(TransferListener transferListener);
234
235 /**
236 * Sets the system properties to use, e.g. for processing of artifact descriptors. System properties are usually
237 * collected from the runtime environment like {@link System#getProperties()} and environment variables.
238 * <p>
239 * <em>Note:</em> System properties are of type {@code Map<String, String>} and any key-value pair in the input map
240 * that doesn't match this type will be silently ignored.
241 *
242 * @param systemProperties The system properties, may be {@code null} or empty if none.
243 * @return This session for chaining, never {@code null}.
244 */
245 SessionBuilder setSystemProperties(Map<?, ?> systemProperties);
246
247 /**
248 * Sets the specified system property.
249 *
250 * @param key The property key, must not be {@code null}.
251 * @param value The property value, may be {@code null} to remove/unset the property.
252 * @return This session for chaining, never {@code null}.
253 */
254 SessionBuilder setSystemProperty(String key, String value);
255
256 /**
257 * Sets the user properties to use, e.g. for processing of artifact descriptors. User properties are similar to
258 * system properties but are set on the discretion of the user and hence are considered of higher priority than
259 * system properties in case of conflicts.
260 * <p>
261 * <em>Note:</em> User properties are of type {@code Map<String, String>} and any key-value pair in the input map
262 * that doesn't match this type will be silently ignored.
263 *
264 * @param userProperties The user properties, may be {@code null} or empty if none.
265 * @return This session for chaining, never {@code null}.
266 */
267 SessionBuilder setUserProperties(Map<?, ?> userProperties);
268
269 /**
270 * Sets the specified user property.
271 *
272 * @param key The property key, must not be {@code null}.
273 * @param value The property value, may be {@code null} to remove/unset the property.
274 * @return This session for chaining, never {@code null}.
275 */
276 SessionBuilder setUserProperty(String key, String value);
277
278 /**
279 * Sets the configuration properties used to tweak internal aspects of the repository system (e.g. thread pooling,
280 * connector-specific behavior, etc.).
281 * <p>
282 * <em>Note:</em> Configuration properties are of type {@code Map<String, Object>} and any key-value pair in the
283 * input map that doesn't match this type will be silently ignored.
284 *
285 * @param configProperties The configuration properties, may be {@code null} or empty if none.
286 * @return This session for chaining, never {@code null}.
287 */
288 SessionBuilder setConfigProperties(Map<?, ?> configProperties);
289
290 /**
291 * Sets the specified configuration property.
292 *
293 * @param key The property key, must not be {@code null}.
294 * @param value The property value, may be {@code null} to remove/unset the property.
295 * @return This session for chaining, never {@code null}.
296 */
297 SessionBuilder setConfigProperty(String key, Object value);
298
299 /**
300 * Sets the mirror selector to use for repositories discovered in artifact descriptors. Note that this selector is
301 * not used for remote repositories which are passed as request parameters to the repository system, those
302 * repositories are supposed to denote the effective repositories.
303 *
304 * @param mirrorSelector The mirror selector to use, may be {@code null}.
305 * @return This session for chaining, never {@code null}.
306 */
307 SessionBuilder setMirrorSelector(MirrorSelector mirrorSelector);
308
309 /**
310 * Sets the proxy selector to use for repositories discovered in artifact descriptors. Note that this selector is
311 * not used for remote repositories which are passed as request parameters to the repository system, those
312 * repositories are supposed to have their proxy (if any) already set.
313 *
314 * @param proxySelector The proxy selector to use, may be {@code null}.
315 * @return This session for chaining, never {@code null}.
316 * @see RemoteRepository#getProxy()
317 */
318 SessionBuilder setProxySelector(ProxySelector proxySelector);
319
320 /**
321 * Sets the authentication selector to use for repositories discovered in artifact descriptors. Note that this
322 * selector is not used for remote repositories which are passed as request parameters to the repository system,
323 * those repositories are supposed to have their authentication (if any) already set.
324 *
325 * @param authenticationSelector The authentication selector to use, may be {@code null}.
326 * @return This session for chaining, never {@code null}.
327 * @see RemoteRepository#getAuthentication()
328 */
329 SessionBuilder setAuthenticationSelector(AuthenticationSelector authenticationSelector);
330
331 /**
332 * Sets the registry of artifact types recognized by this session.
333 *
334 * @param artifactTypeRegistry The artifact type registry, may be {@code null}.
335 * @return This session for chaining, never {@code null}.
336 */
337 SessionBuilder setArtifactTypeRegistry(ArtifactTypeRegistry artifactTypeRegistry);
338
339 /**
340 * Sets the dependency traverser to use for building dependency graphs.
341 *
342 * @param dependencyTraverser The dependency traverser to use for building dependency graphs, may be {@code null}.
343 * @return This session for chaining, never {@code null}.
344 */
345 SessionBuilder setDependencyTraverser(DependencyTraverser dependencyTraverser);
346
347 /**
348 * Sets the dependency manager to use for building dependency graphs.
349 *
350 * @param dependencyManager The dependency manager to use for building dependency graphs, may be {@code null}.
351 * @return This session for chaining, never {@code null}.
352 */
353 SessionBuilder setDependencyManager(DependencyManager dependencyManager);
354
355 /**
356 * Sets the dependency selector to use for building dependency graphs.
357 *
358 * @param dependencySelector The dependency selector to use for building dependency graphs, may be {@code null}.
359 * @return This session for chaining, never {@code null}.
360 */
361 SessionBuilder setDependencySelector(DependencySelector dependencySelector);
362
363 /**
364 * Sets the version filter to use for building dependency graphs.
365 *
366 * @param versionFilter The version filter to use for building dependency graphs, may be {@code null} to not filter
367 * versions.
368 * @return This session for chaining, never {@code null}.
369 */
370 SessionBuilder setVersionFilter(VersionFilter versionFilter);
371
372 /**
373 * Sets the dependency graph transformer to use for building dependency graphs.
374 *
375 * @param dependencyGraphTransformer The dependency graph transformer to use for building dependency graphs, may be
376 * {@code null}.
377 * @return This session for chaining, never {@code null}.
378 */
379 SessionBuilder setDependencyGraphTransformer(DependencyGraphTransformer dependencyGraphTransformer);
380
381 /**
382 * Sets the custom data associated with this session.
383 * Note: When this method used to set instance, same passed instance will be used for every built session out
384 * of this builder instance, hence the built sessions will share these instances as well!
385 *
386 * @param data The session data, may be {@code null}.
387 * @return This session for chaining, never {@code null}.
388 */
389 SessionBuilder setData(SessionData data);
390
391 /**
392 * Sets the cache the repository system may use to save data for future reuse during the session.
393 * Note: When this method used to set instance, same passed instance will be used for every built session out
394 * of this builder instance, hence the built sessions will share these instances as well!
395 *
396 * @param cache The repository cache, may be {@code null} if none.
397 * @return This session for chaining, never {@code null}.
398 */
399 SessionBuilder setCache(RepositoryCache cache);
400
401 /**
402 * Sets the scope manager for session, may be {@code null}.
403 *
404 * @param scopeManager The scope manager, may be {@code null}.
405 * @return The session for chaining, never {@code null}.
406 */
407 SessionBuilder setScopeManager(ScopeManager scopeManager);
408
409 /**
410 * Sets the dependency collection checker, may be {@code null}.
411 *
412 * @param dependencyCollectionChecker The checker instance, may be {@code null}.
413 * @return The session for chaining, may be {@code null}.
414 * @since 2.0.19
415 */
416 SessionBuilder setDependencyCollectionChecker(DependencyCollectionChecker dependencyCollectionChecker);
417
418 /**
419 * Adds on session ended handler to be immediately registered when this builder creates session.
420 *
421 * @param handler The on session ended handler, may not be {@code null}.
422 * @return The session for chaining, never {@code null}.
423 */
424 SessionBuilder addOnSessionEndedHandler(Runnable handler);
425
426 /**
427 * Sets the custom session data supplier associated with this session.
428 * Note: The supplier will be used for every built session out of this builder instance, so if supplier supplies
429 * <em>same instance</em> the built sessions will share these instances as well!
430 *
431 * @param dataSupplier The session data supplier, may not be {@code null}.
432 * @return This session for chaining, never {@code null}.
433 */
434 SessionBuilder setSessionDataSupplier(Supplier<SessionData> dataSupplier);
435
436 /**
437 * Sets the cache supplier for the repository system may use to save data for future reuse during the session.
438 * Note: The supplier will be used for every built session out of this builder instance, so if supplier supplies
439 * <em>same instance</em> the built sessions will share these instances as well!
440 *
441 * @param cacheSupplier The repository cache supplier, may not be {@code null}.
442 * @return This session for chaining, never {@code null}.
443 */
444 SessionBuilder setRepositoryCacheSupplier(Supplier<RepositoryCache> cacheSupplier);
445
446 /**
447 * Shortcut method to set up local repository manager directly onto builder. There must be at least one non-null
448 * {@link Path} passed in this method. In case multiple files, session builder will use chained local repository
449 * manager.
450 *
451 * @param baseDirectories The local repository base directories.
452 * @return This session for chaining, never {@code null}.
453 * @see #withLocalRepositories(LocalRepository...)
454 */
455 SessionBuilder withLocalRepositoryBaseDirectories(Path... baseDirectories);
456
457 /**
458 * Shortcut method to set up local repository manager directly onto builder. There must be at least one non-null
459 * {@link Path} present in passed in list. In case multiple files, session builder will use chained local
460 * repository manager.
461 *
462 * @param baseDirectories The local repository base directories.
463 * @return This session for chaining, never {@code null}.
464 * @see #withLocalRepositories(Collection)
465 */
466 SessionBuilder withLocalRepositoryBaseDirectories(Collection<Path> baseDirectories);
467
468 /**
469 * Shortcut method to set up local repository manager directly onto builder. There must be at least one non-null
470 * {@link LocalRepository} passed in this method. In case multiple local repositories, session builder will
471 * use chained local repository manager.
472 *
473 * @param localRepositories The local repositories.
474 * @return This session for chaining, never {@code null}.
475 */
476 SessionBuilder withLocalRepositories(LocalRepository... localRepositories);
477
478 /**
479 * Shortcut method to set up local repository manager directly onto builder. There must be at least one non-null
480 * {@link LocalRepository} present in passed in list. In case multiple local repositories, session builder will
481 * use chained local repository manager.
482 *
483 * @param localRepositories The local repositories.
484 * @return This session for chaining, never {@code null}.
485 */
486 SessionBuilder withLocalRepositories(Collection<LocalRepository> localRepositories);
487
488 /**
489 * Adds the listeners to be notified of actions in the repository system.
490 *
491 * @param repositoryListeners The repository listeners, never {@code null}.
492 * @return This session for chaining, never {@code null}.
493 */
494 SessionBuilder withRepositoryListener(RepositoryListener... repositoryListeners);
495
496 /**
497 * Adds the listeners to be notified of actions in the repository system.
498 *
499 * @param repositoryListeners The repository listeners, never {@code null}.
500 * @return This session for chaining, never {@code null}.
501 */
502 SessionBuilder withRepositoryListener(Collection<RepositoryListener> repositoryListeners);
503
504 /**
505 * Adds the listener to be notified of uploads/downloads by the repository system.
506 *
507 * @param transferListeners The transfer listeners, never {@code null}.
508 * @return This session for chaining, never {@code null}.
509 */
510 SessionBuilder withTransferListener(TransferListener... transferListeners);
511
512 /**
513 * Adds the listener to be notified of uploads/downloads by the repository system.
514 *
515 * @param transferListeners The transfer listeners, never {@code null}.
516 * @return This session for chaining, never {@code null}.
517 */
518 SessionBuilder withTransferListener(Collection<TransferListener> transferListeners);
519
520 /**
521 * Shortcut method to shallow-copy passed in session into current builder.
522 *
523 * @param session The session to shallow-copy from.
524 * @return This session for chaining, never {@code null}.
525 */
526 SessionBuilder withRepositorySystemSession(RepositorySystemSession session);
527
528 /**
529 * Creates immutable closeable session out this builder instance.
530 *
531 * @return Immutable closeable session, never {@code null}.
532 */
533 CloseableSession build();
534 }
535
536 /**
537 * Indicates whether the repository system operates in offline mode and avoids/refuses any access to remote
538 * repositories.
539 *
540 * @return {@code true} if the repository system is in offline mode, {@code false} otherwise.
541 */
542 boolean isOffline();
543
544 /**
545 * Indicates whether repositories declared in artifact descriptors should be ignored during transitive dependency
546 * collection. If enabled, only the repositories originally provided with the collect request will be considered.
547 *
548 * @return {@code true} if additional repositories from artifact descriptors are ignored, {@code false} to merge
549 * those with the originally specified repositories.
550 */
551 boolean isIgnoreArtifactDescriptorRepositories();
552
553 /**
554 * Gets the policy which controls whether resolutions errors from remote repositories should be cached.
555 *
556 * @return The resolution error policy for this session or {@code null} if resolution errors should generally not be
557 * cached.
558 */
559 ResolutionErrorPolicy getResolutionErrorPolicy();
560
561 /**
562 * Gets the policy which controls how errors related to reading artifact descriptors should be handled.
563 *
564 * @return The descriptor error policy for this session or {@code null} if descriptor errors should generally not be
565 * tolerated.
566 */
567 ArtifactDescriptorPolicy getArtifactDescriptorPolicy();
568
569 /**
570 * Gets the global checksum policy. If set, the global checksum policy overrides the checksum policies of the remote
571 * repositories being used for resolution.
572 *
573 * @return The global checksum policy or {@code null}/empty if not set and the per-repository policies apply.
574 * @see RepositoryPolicy#CHECKSUM_POLICY_FAIL
575 * @see RepositoryPolicy#CHECKSUM_POLICY_IGNORE
576 * @see RepositoryPolicy#CHECKSUM_POLICY_WARN
577 */
578 String getChecksumPolicy();
579
580 /**
581 * Gets the global update policy, or {@code null} if not set.
582 * <p>
583 * This method is meant for code that does not want to distinguish between artifact and metadata policies.
584 * Note: applications should either use get/set updatePolicy (this method and
585 * {@link DefaultRepositorySystemSession#setUpdatePolicy(String)}) or also distinguish between artifact and
586 * metadata update policies (and use other methods), but <em>should not mix the two!</em>
587 *
588 * @see #getArtifactUpdatePolicy()
589 * @see #getMetadataUpdatePolicy()
590 * @return The global update policy, or {@code null} if not set.
591 */
592 String getUpdatePolicy();
593
594 /**
595 * Gets the global artifact update policy. If set, the global update policy overrides the update policies of the
596 * remote repositories being used for resolution.
597 *
598 * @return The global update policy or {@code null}/empty if not set and the per-repository policies apply.
599 * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
600 * @see RepositoryPolicy#UPDATE_POLICY_DAILY
601 * @see RepositoryPolicy#UPDATE_POLICY_NEVER
602 * @since 2.0.0
603 */
604 String getArtifactUpdatePolicy();
605
606 /**
607 * Gets the global metadata update policy. If set, the global update policy overrides the update policies of the remote
608 * repositories being used for resolution.
609 *
610 * @return The global update policy or {@code null}/empty if not set and the per-repository policies apply.
611 * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
612 * @see RepositoryPolicy#UPDATE_POLICY_DAILY
613 * @see RepositoryPolicy#UPDATE_POLICY_NEVER
614 * @since 2.0.0
615 */
616 String getMetadataUpdatePolicy();
617
618 /**
619 * Gets the local repository used during this session. This is a convenience method for
620 * {@link LocalRepositoryManager#getRepository()}.
621 *
622 * @return The local repository being during this session, never {@code null}.
623 */
624 LocalRepository getLocalRepository();
625
626 /**
627 * Gets the local repository manager used during this session.
628 *
629 * @return The local repository manager used during this session, never {@code null}.
630 */
631 LocalRepositoryManager getLocalRepositoryManager();
632
633 /**
634 * Gets the workspace reader used during this session. If set, the workspace reader will usually be consulted first
635 * to resolve artifacts.
636 *
637 * @return The workspace reader for this session or {@code null} if none.
638 */
639 WorkspaceReader getWorkspaceReader();
640
641 /**
642 * Gets the listener being notified of actions in the repository system.
643 *
644 * @return The repository listener or {@code null} if none.
645 */
646 RepositoryListener getRepositoryListener();
647
648 /**
649 * Gets the listener being notified of uploads/downloads by the repository system.
650 *
651 * @return The transfer listener or {@code null} if none.
652 */
653 TransferListener getTransferListener();
654
655 /**
656 * Gets the system properties to use, e.g. for processing of artifact descriptors. System properties are usually
657 * collected from the runtime environment like {@link System#getProperties()} and environment variables.
658 *
659 * @return The (read-only) system properties, never {@code null}.
660 */
661 Map<String, String> getSystemProperties();
662
663 /**
664 * Gets the user properties to use, e.g. for processing of artifact descriptors. User properties are similar to
665 * system properties but are set on the discretion of the user and hence are considered of higher priority than
666 * system properties.
667 *
668 * @return The (read-only) user properties, never {@code null}.
669 */
670 Map<String, String> getUserProperties();
671
672 /**
673 * Gets the configuration properties used to tweak internal aspects of the repository system (e.g. thread pooling,
674 * connector-specific behavior, etc.)
675 *
676 * @return The (read-only) configuration properties, never {@code null}.
677 * @see ConfigurationProperties
678 */
679 Map<String, Object> getConfigProperties();
680
681 /**
682 * Gets the mirror selector to use for repositories discovered in artifact descriptors. Note that this selector is
683 * not used for remote repositories which are passed as request parameters to the repository system, those
684 * repositories are supposed to denote the effective repositories.
685 *
686 * @return The mirror selector to use, never {@code null}.
687 * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
688 */
689 MirrorSelector getMirrorSelector();
690
691 /**
692 * Gets the proxy selector to use for repositories discovered in artifact descriptors. Note that this selector is
693 * not used for remote repositories which are passed as request parameters to the repository system, those
694 * repositories are supposed to have their proxy (if any) already set.
695 *
696 * @return The proxy selector to use, never {@code null}.
697 * @see org.eclipse.aether.repository.RemoteRepository#getProxy()
698 * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
699 */
700 ProxySelector getProxySelector();
701
702 /**
703 * Gets the authentication selector to use for repositories discovered in artifact descriptors. Note that this
704 * selector is not used for remote repositories which are passed as request parameters to the repository system,
705 * those repositories are supposed to have their authentication (if any) already set.
706 *
707 * @return The authentication selector to use, never {@code null}.
708 * @see org.eclipse.aether.repository.RemoteRepository#getAuthentication()
709 * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
710 */
711 AuthenticationSelector getAuthenticationSelector();
712
713 /**
714 * Gets the registry of artifact types recognized by this session, for instance when processing artifact
715 * descriptors.
716 *
717 * @return The artifact type registry, never {@code null}.
718 */
719 ArtifactTypeRegistry getArtifactTypeRegistry();
720
721 /**
722 * Gets the dependency traverser to use for building dependency graphs.
723 *
724 * @return The dependency traverser to use for building dependency graphs or {@code null} if dependencies are
725 * unconditionally traversed.
726 */
727 DependencyTraverser getDependencyTraverser();
728
729 /**
730 * Gets the dependency manager to use for building dependency graphs.
731 *
732 * @return The dependency manager to use for building dependency graphs or {@code null} if dependency management is
733 * not performed.
734 */
735 DependencyManager getDependencyManager();
736
737 /**
738 * Gets the dependency selector to use for building dependency graphs.
739 *
740 * @return The dependency selector to use for building dependency graphs or {@code null} if dependencies are
741 * unconditionally included.
742 */
743 DependencySelector getDependencySelector();
744
745 /**
746 * Gets the version filter to use for building dependency graphs.
747 *
748 * @return The version filter to use for building dependency graphs or {@code null} if versions aren't filtered.
749 */
750 VersionFilter getVersionFilter();
751
752 /**
753 * Gets the dependency graph transformer to use for building dependency graphs.
754 *
755 * @return The dependency graph transformer to use for building dependency graphs or {@code null} if none.
756 */
757 DependencyGraphTransformer getDependencyGraphTransformer();
758
759 /**
760 * Gets the custom data associated with this session.
761 *
762 * @return The session data, never {@code null}.
763 */
764 SessionData getData();
765
766 /**
767 * Gets the cache the repository system may use to save data for future reuse during the session.
768 *
769 * @return The repository cache or {@code null} if none.
770 */
771 RepositoryCache getCache();
772
773 /**
774 * Returns the scope manager to be used in this session, may be {@code null} if not set.
775 *
776 * @return The scope manager or {@code null} if not set.
777 * @since 2.0.0
778 */
779 ScopeManager getScopeManager();
780
781 /**
782 * Returns the system dependency scope.
783 * <p>
784 * Shorthand method for {@link ScopeManager#getSystemDependencyScope()}.
785 * <p>
786 * If {@link ScopeManager} is set, {@link #getScopeManager()} returns non-null value, the result of
787 * {@link ScopeManager#getSystemDependencyScope()} is returned (that may be {@code null}). If no {@link ScopeManager}
788 * if set, then {@link SystemDependencyScope#LEGACY} instance is returned, as lack of scope manager means that
789 * resolver operates in "legacy" mode (Maven3 compatible mode).
790 *
791 * @return The system dependency scope or {@code null} if no such scope.
792 * @since 2.0.0
793 */
794 SystemDependencyScope getSystemDependencyScope();
795
796 /**
797 * Returns the dependency collector checker, may be {@code null}.
798 *
799 * @return The effective {@link DependencyCollectionChecker} instance, may be {@code null}.
800 * @since 2.0.19
801 */
802 DependencyCollectionChecker getDependencyCollectionChecker();
803
804 /**
805 * Registers a handler to execute when this session closed.
806 * <p>
807 * Note: Resolver 1.x sessions will not be able to register handlers. Migrate to Resolver 2.x way of handling
808 * sessions to make full use of new features. New features (like HTTP/2 transport) depend on this functionality.
809 * While they will function with Resolver 1.x sessions, they may produce resource leaks.
810 *
811 * @param handler the handler, never {@code null}.
812 * @return {@code true} if handler successfully registered, {@code false} otherwise.
813 * @since 2.0.0
814 */
815 boolean addOnSessionEndedHandler(Runnable handler);
816 }