View Javadoc
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.util.Map;
22  
23  import org.eclipse.aether.artifact.ArtifactTypeRegistry;
24  import org.eclipse.aether.collection.DependencyGraphTransformer;
25  import org.eclipse.aether.collection.DependencyManager;
26  import org.eclipse.aether.collection.DependencySelector;
27  import org.eclipse.aether.collection.DependencyTraverser;
28  import org.eclipse.aether.collection.VersionFilter;
29  import org.eclipse.aether.repository.AuthenticationSelector;
30  import org.eclipse.aether.repository.LocalRepository;
31  import org.eclipse.aether.repository.LocalRepositoryManager;
32  import org.eclipse.aether.repository.MirrorSelector;
33  import org.eclipse.aether.repository.ProxySelector;
34  import org.eclipse.aether.repository.RepositoryPolicy;
35  import org.eclipse.aether.repository.WorkspaceReader;
36  import org.eclipse.aether.resolution.ArtifactDescriptorPolicy;
37  import org.eclipse.aether.resolution.ResolutionErrorPolicy;
38  import org.eclipse.aether.transfer.TransferListener;
39  import org.eclipse.aether.transform.FileTransformerManager;
40  
41  /**
42   * Defines settings and components that control the repository system. Once initialized, the session object itself is
43   * supposed to be immutable and hence can safely be shared across an entire application and any concurrent threads
44   * reading it. Components that wish to tweak some aspects of an existing session should use the copy constructor of
45   * {@link DefaultRepositorySystemSession} and its mutators to derive a custom session.
46   *
47   * @noimplement This interface is not intended to be implemented by clients.
48   * @noextend This interface is not intended to be extended by clients.
49   */
50  public interface RepositorySystemSession {
51  
52      /**
53       * Indicates whether the repository system operates in offline mode and avoids/refuses any access to remote
54       * repositories.
55       *
56       * @return {@code true} if the repository system is in offline mode, {@code false} otherwise.
57       */
58      boolean isOffline();
59  
60      /**
61       * Indicates whether repositories declared in artifact descriptors should be ignored during transitive dependency
62       * collection. If enabled, only the repositories originally provided with the collect request will be considered.
63       *
64       * @return {@code true} if additional repositories from artifact descriptors are ignored, {@code false} to merge
65       *         those with the originally specified repositories.
66       */
67      boolean isIgnoreArtifactDescriptorRepositories();
68  
69      /**
70       * Gets the policy which controls whether resolutions errors from remote repositories should be cached.
71       *
72       * @return The resolution error policy for this session or {@code null} if resolution errors should generally not be
73       *         cached.
74       */
75      ResolutionErrorPolicy getResolutionErrorPolicy();
76  
77      /**
78       * Gets the policy which controls how errors related to reading artifact descriptors should be handled.
79       *
80       * @return The descriptor error policy for this session or {@code null} if descriptor errors should generally not be
81       *         tolerated.
82       */
83      ArtifactDescriptorPolicy getArtifactDescriptorPolicy();
84  
85      /**
86       * Gets the global checksum policy. If set, the global checksum policy overrides the checksum policies of the remote
87       * repositories being used for resolution.
88       *
89       * @return The global checksum policy or {@code null}/empty if not set and the per-repository policies apply.
90       * @see RepositoryPolicy#CHECKSUM_POLICY_FAIL
91       * @see RepositoryPolicy#CHECKSUM_POLICY_IGNORE
92       * @see RepositoryPolicy#CHECKSUM_POLICY_WARN
93       */
94      String getChecksumPolicy();
95  
96      /**
97       * Gets the global update policy. If set, the global update policy overrides the update policies of the remote
98       * repositories being used for resolution.
99       *
100      * @return The global update policy or {@code null}/empty if not set and the per-repository policies apply.
101      * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
102      * @see RepositoryPolicy#UPDATE_POLICY_DAILY
103      * @see RepositoryPolicy#UPDATE_POLICY_NEVER
104      */
105     String getUpdatePolicy();
106 
107     /**
108      * Gets the local repository used during this session. This is a convenience method for
109      * {@link LocalRepositoryManager#getRepository()}.
110      *
111      * @return The local repository being during this session, never {@code null}.
112      */
113     LocalRepository getLocalRepository();
114 
115     /**
116      * Gets the local repository manager used during this session.
117      *
118      * @return The local repository manager used during this session, never {@code null}.
119      */
120     LocalRepositoryManager getLocalRepositoryManager();
121 
122     /**
123      * Gets the workspace reader used during this session. If set, the workspace reader will usually be consulted first
124      * to resolve artifacts.
125      *
126      * @return The workspace reader for this session or {@code null} if none.
127      */
128     WorkspaceReader getWorkspaceReader();
129 
130     /**
131      * Gets the listener being notified of actions in the repository system.
132      *
133      * @return The repository listener or {@code null} if none.
134      */
135     RepositoryListener getRepositoryListener();
136 
137     /**
138      * Gets the listener being notified of uploads/downloads by the repository system.
139      *
140      * @return The transfer listener or {@code null} if none.
141      */
142     TransferListener getTransferListener();
143 
144     /**
145      * Gets the system properties to use, e.g. for processing of artifact descriptors. System properties are usually
146      * collected from the runtime environment like {@link System#getProperties()} and environment variables.
147      *
148      * @return The (read-only) system properties, never {@code null}.
149      */
150     Map<String, String> getSystemProperties();
151 
152     /**
153      * Gets the user properties to use, e.g. for processing of artifact descriptors. User properties are similar to
154      * system properties but are set on the discretion of the user and hence are considered of higher priority than
155      * system properties.
156      *
157      * @return The (read-only) user properties, never {@code null}.
158      */
159     Map<String, String> getUserProperties();
160 
161     /**
162      * Gets the configuration properties used to tweak internal aspects of the repository system (e.g. thread pooling,
163      * connector-specific behavior, etc.)
164      *
165      * @return The (read-only) configuration properties, never {@code null}.
166      * @see ConfigurationProperties
167      */
168     Map<String, Object> getConfigProperties();
169 
170     /**
171      * Gets the mirror selector to use for repositories discovered in artifact descriptors. Note that this selector is
172      * not used for remote repositories which are passed as request parameters to the repository system, those
173      * repositories are supposed to denote the effective repositories.
174      *
175      * @return The mirror selector to use, never {@code null}.
176      * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
177      */
178     MirrorSelector getMirrorSelector();
179 
180     /**
181      * Gets the proxy selector to use for repositories discovered in artifact descriptors. Note that this selector is
182      * not used for remote repositories which are passed as request parameters to the repository system, those
183      * repositories are supposed to have their proxy (if any) already set.
184      *
185      * @return The proxy selector to use, never {@code null}.
186      * @see org.eclipse.aether.repository.RemoteRepository#getProxy()
187      * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
188      */
189     ProxySelector getProxySelector();
190 
191     /**
192      * Gets the authentication selector to use for repositories discovered in artifact descriptors. Note that this
193      * selector is not used for remote repositories which are passed as request parameters to the repository system,
194      * those repositories are supposed to have their authentication (if any) already set.
195      *
196      * @return The authentication selector to use, never {@code null}.
197      * @see org.eclipse.aether.repository.RemoteRepository#getAuthentication()
198      * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
199      */
200     AuthenticationSelector getAuthenticationSelector();
201 
202     /**
203      * Gets the registry of artifact types recognized by this session, for instance when processing artifact
204      * descriptors.
205      *
206      * @return The artifact type registry, never {@code null}.
207      */
208     ArtifactTypeRegistry getArtifactTypeRegistry();
209 
210     /**
211      * Gets the dependency traverser to use for building dependency graphs.
212      *
213      * @return The dependency traverser to use for building dependency graphs or {@code null} if dependencies are
214      *         unconditionally traversed.
215      */
216     DependencyTraverser getDependencyTraverser();
217 
218     /**
219      * Gets the dependency manager to use for building dependency graphs.
220      *
221      * @return The dependency manager to use for building dependency graphs or {@code null} if dependency management is
222      *         not performed.
223      */
224     DependencyManager getDependencyManager();
225 
226     /**
227      * Gets the dependency selector to use for building dependency graphs.
228      *
229      * @return The dependency selector to use for building dependency graphs or {@code null} if dependencies are
230      *         unconditionally included.
231      */
232     DependencySelector getDependencySelector();
233 
234     /**
235      * Gets the version filter to use for building dependency graphs.
236      *
237      * @return The version filter to use for building dependency graphs or {@code null} if versions aren't filtered.
238      */
239     VersionFilter getVersionFilter();
240 
241     /**
242      * Gets the dependency graph transformer to use for building dependency graphs.
243      *
244      * @return The dependency graph transformer to use for building dependency graphs or {@code null} if none.
245      */
246     DependencyGraphTransformer getDependencyGraphTransformer();
247 
248     /**
249      * Gets the custom data associated with this session.
250      *
251      * @return The session data, never {@code null}.
252      */
253     SessionData getData();
254 
255     /**
256      * Gets the cache the repository system may use to save data for future reuse during the session.
257      *
258      * @return The repository cache or {@code null} if none.
259      */
260     RepositoryCache getCache();
261 
262     /**
263      * Get the file transformer manager
264      *
265      * @return the manager, never {@code null}
266      * @deprecated Without any direct replacement for now. This API is OOM-prone, and also lacks a lot of context about
267      * transforming.
268      */
269     @Deprecated
270     FileTransformerManager getFileTransformerManager();
271 }