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;
039import org.eclipse.aether.transform.FileTransformerManager;
040
041/**
042 * Defines settings and components that control the repository system. Once initialized, the session object itself is
043 * supposed to be immutable and hence can safely be shared across an entire application and any concurrent threads
044 * reading it. Components that wish to tweak some aspects of an existing session should use the copy constructor of
045 * {@link DefaultRepositorySystemSession} and its mutators to derive a custom session.
046 *
047 * @noimplement This interface is not intended to be implemented by clients.
048 * @noextend This interface is not intended to be extended by clients.
049 */
050public interface RepositorySystemSession {
051
052    /**
053     * Indicates whether the repository system operates in offline mode and avoids/refuses any access to remote
054     * repositories.
055     *
056     * @return {@code true} if the repository system is in offline mode, {@code false} otherwise.
057     */
058    boolean isOffline();
059
060    /**
061     * Indicates whether repositories declared in artifact descriptors should be ignored during transitive dependency
062     * collection. If enabled, only the repositories originally provided with the collect request will be considered.
063     *
064     * @return {@code true} if additional repositories from artifact descriptors are ignored, {@code false} to merge
065     *         those with the originally specified repositories.
066     */
067    boolean isIgnoreArtifactDescriptorRepositories();
068
069    /**
070     * Gets the policy which controls whether resolutions errors from remote repositories should be cached.
071     *
072     * @return The resolution error policy for this session or {@code null} if resolution errors should generally not be
073     *         cached.
074     */
075    ResolutionErrorPolicy getResolutionErrorPolicy();
076
077    /**
078     * Gets the policy which controls how errors related to reading artifact descriptors should be handled.
079     *
080     * @return The descriptor error policy for this session or {@code null} if descriptor errors should generally not be
081     *         tolerated.
082     */
083    ArtifactDescriptorPolicy getArtifactDescriptorPolicy();
084
085    /**
086     * Gets the global checksum policy. If set, the global checksum policy overrides the checksum policies of the remote
087     * repositories being used for resolution.
088     *
089     * @return The global checksum policy or {@code null}/empty if not set and the per-repository policies apply.
090     * @see RepositoryPolicy#CHECKSUM_POLICY_FAIL
091     * @see RepositoryPolicy#CHECKSUM_POLICY_IGNORE
092     * @see RepositoryPolicy#CHECKSUM_POLICY_WARN
093     */
094    String getChecksumPolicy();
095
096    /**
097     * Gets the global update policy. If set, the global update policy overrides the update policies of the remote
098     * repositories being used for resolution.
099     *
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}