001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether;
020
021import java.util.Map;
022
023import org.eclipse.aether.artifact.ArtifactTypeRegistry;
024import org.eclipse.aether.collection.DependencyGraphTransformer;
025import org.eclipse.aether.collection.DependencyManager;
026import org.eclipse.aether.collection.DependencySelector;
027import org.eclipse.aether.collection.DependencyTraverser;
028import org.eclipse.aether.collection.VersionFilter;
029import org.eclipse.aether.repository.AuthenticationSelector;
030import org.eclipse.aether.repository.LocalRepository;
031import org.eclipse.aether.repository.LocalRepositoryManager;
032import org.eclipse.aether.repository.MirrorSelector;
033import org.eclipse.aether.repository.ProxySelector;
034import org.eclipse.aether.repository.RepositoryPolicy;
035import org.eclipse.aether.repository.WorkspaceReader;
036import org.eclipse.aether.resolution.ArtifactDescriptorPolicy;
037import org.eclipse.aether.resolution.ResolutionErrorPolicy;
038import org.eclipse.aether.transfer.TransferListener;
039
040/**
041 * Defines settings and components that control the repository system. Once initialized, the session object itself is
042 * supposed to be immutable and hence can safely be shared across an entire application and any concurrent threads
043 * reading it. Components that wish to tweak some aspects of an existing session should use the copy constructor of
044 * {@link DefaultRepositorySystemSession} and its mutators to derive a custom session.
045 *
046 * @noimplement This interface is not intended to be implemented by clients.
047 * @noextend This interface is not intended to be extended by clients.
048 */
049public interface RepositorySystemSession {
050
051    /**
052     * Indicates whether the repository system operates in offline mode and avoids/refuses any access to remote
053     * repositories.
054     *
055     * @return {@code true} if the repository system is in offline mode, {@code false} otherwise.
056     */
057    boolean isOffline();
058
059    /**
060     * Indicates whether repositories declared in artifact descriptors should be ignored during transitive dependency
061     * collection. If enabled, only the repositories originally provided with the collect request will be considered.
062     *
063     * @return {@code true} if additional repositories from artifact descriptors are ignored, {@code false} to merge
064     *         those with the originally specified repositories.
065     */
066    boolean isIgnoreArtifactDescriptorRepositories();
067
068    /**
069     * Gets the policy which controls whether resolutions errors from remote repositories should be cached.
070     *
071     * @return The resolution error policy for this session or {@code null} if resolution errors should generally not be
072     *         cached.
073     */
074    ResolutionErrorPolicy getResolutionErrorPolicy();
075
076    /**
077     * Gets the policy which controls how errors related to reading artifact descriptors should be handled.
078     *
079     * @return The descriptor error policy for this session or {@code null} if descriptor errors should generally not be
080     *         tolerated.
081     */
082    ArtifactDescriptorPolicy getArtifactDescriptorPolicy();
083
084    /**
085     * Gets the global checksum policy. If set, the global checksum policy overrides the checksum policies of the remote
086     * repositories being used for resolution.
087     *
088     * @return The global checksum policy or {@code null}/empty if not set and the per-repository policies apply.
089     * @see RepositoryPolicy#CHECKSUM_POLICY_FAIL
090     * @see RepositoryPolicy#CHECKSUM_POLICY_IGNORE
091     * @see RepositoryPolicy#CHECKSUM_POLICY_WARN
092     */
093    String getChecksumPolicy();
094
095    /**
096     * Gets the global update policy, or {@code null} if not set.
097     * <p>
098     * This method is meant for code that does not want to distinguish between artifact and metadata policies.
099     * 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}