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