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