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