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;
040import org.eclipse.aether.transform.FileTransformerManager;
041
042/**
043 * Defines settings and components that control the repository system. Once initialized, the session object itself is
044 * supposed to be immutable and hence can safely be shared across an entire application and any concurrent threads
045 * reading it. Components that wish to tweak some aspects of an existing session should use the copy constructor of
046 * {@link DefaultRepositorySystemSession} and its mutators to derive a custom session.
047 * 
048 * @noimplement This interface is not intended to be implemented by clients.
049 * @noextend This interface is not intended to be extended by clients.
050 */
051public interface RepositorySystemSession
052{
053
054    /**
055     * Indicates whether the repository system operates in offline mode and avoids/refuses any access to remote
056     * repositories.
057     * 
058     * @return {@code true} if the repository system is in offline mode, {@code false} otherwise.
059     */
060    boolean isOffline();
061
062    /**
063     * Indicates whether repositories declared in artifact descriptors should be ignored during transitive dependency
064     * collection. If enabled, only the repositories originally provided with the collect request will be considered.
065     * 
066     * @return {@code true} if additional repositories from artifact descriptors are ignored, {@code false} to merge
067     *         those with the originally specified repositories.
068     */
069    boolean isIgnoreArtifactDescriptorRepositories();
070
071    /**
072     * Gets the policy which controls whether resolutions errors from remote repositories should be cached.
073     * 
074     * @return The resolution error policy for this session or {@code null} if resolution errors should generally not be
075     *         cached.
076     */
077    ResolutionErrorPolicy getResolutionErrorPolicy();
078
079    /**
080     * Gets the policy which controls how errors related to reading artifact descriptors should be handled.
081     * 
082     * @return The descriptor error policy for this session or {@code null} if descriptor errors should generally not be
083     *         tolerated.
084     */
085    ArtifactDescriptorPolicy getArtifactDescriptorPolicy();
086
087    /**
088     * Gets the global checksum policy. If set, the global checksum policy overrides the checksum policies of the remote
089     * repositories being used for resolution.
090     * 
091     * @return The global checksum policy or {@code null}/empty if not set and the per-repository policies apply.
092     * @see RepositoryPolicy#CHECKSUM_POLICY_FAIL
093     * @see RepositoryPolicy#CHECKSUM_POLICY_IGNORE
094     * @see RepositoryPolicy#CHECKSUM_POLICY_WARN
095     */
096    String getChecksumPolicy();
097
098    /**
099     * Gets the global update policy. If set, the global update policy overrides the update policies of the remote
100     * repositories being used for resolution.
101     * 
102     * @return The global update policy or {@code null}/empty if not set and the per-repository policies apply.
103     * @see RepositoryPolicy#UPDATE_POLICY_ALWAYS
104     * @see RepositoryPolicy#UPDATE_POLICY_DAILY
105     * @see RepositoryPolicy#UPDATE_POLICY_NEVER
106     */
107    String getUpdatePolicy();
108
109    /**
110     * Gets the local repository used during this session. This is a convenience method for
111     * {@link LocalRepositoryManager#getRepository()}.
112     * 
113     * @return The local repository being during this session, never {@code null}.
114     */
115    LocalRepository getLocalRepository();
116
117    /**
118     * Gets the local repository manager used during this session.
119     * 
120     * @return The local repository manager used during this session, never {@code null}.
121     */
122    LocalRepositoryManager getLocalRepositoryManager();
123
124    /**
125     * Gets the workspace reader used during this session. If set, the workspace reader will usually be consulted first
126     * to resolve artifacts.
127     * 
128     * @return The workspace reader for this session or {@code null} if none.
129     */
130    WorkspaceReader getWorkspaceReader();
131
132    /**
133     * Gets the listener being notified of actions in the repository system.
134     * 
135     * @return The repository listener or {@code null} if none.
136     */
137    RepositoryListener getRepositoryListener();
138
139    /**
140     * Gets the listener being notified of uploads/downloads by the repository system.
141     * 
142     * @return The transfer listener or {@code null} if none.
143     */
144    TransferListener getTransferListener();
145
146    /**
147     * Gets the system properties to use, e.g. for processing of artifact descriptors. System properties are usually
148     * collected from the runtime environment like {@link System#getProperties()} and environment variables.
149     * 
150     * @return The (read-only) system properties, never {@code null}.
151     */
152    Map<String, String> getSystemProperties();
153
154    /**
155     * Gets the user properties to use, e.g. for processing of artifact descriptors. User properties are similar to
156     * system properties but are set on the discretion of the user and hence are considered of higher priority than
157     * system properties.
158     * 
159     * @return The (read-only) user properties, never {@code null}.
160     */
161    Map<String, String> getUserProperties();
162
163    /**
164     * Gets the configuration properties used to tweak internal aspects of the repository system (e.g. thread pooling,
165     * connector-specific behavior, etc.)
166     * 
167     * @return The (read-only) configuration properties, never {@code null}.
168     * @see ConfigurationProperties
169     */
170    Map<String, Object> getConfigProperties();
171
172    /**
173     * Gets the mirror selector to use for repositories discovered in artifact descriptors. Note that this selector is
174     * not used for remote repositories which are passed as request parameters to the repository system, those
175     * repositories are supposed to denote the effective repositories.
176     * 
177     * @return The mirror selector to use, never {@code null}.
178     * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
179     */
180    MirrorSelector getMirrorSelector();
181
182    /**
183     * Gets the proxy selector to use for repositories discovered in artifact descriptors. Note that this selector is
184     * not used for remote repositories which are passed as request parameters to the repository system, those
185     * repositories are supposed to have their proxy (if any) already set.
186     * 
187     * @return The proxy selector to use, never {@code null}.
188     * @see org.eclipse.aether.repository.RemoteRepository#getProxy()
189     * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
190     */
191    ProxySelector getProxySelector();
192
193    /**
194     * Gets the authentication selector to use for repositories discovered in artifact descriptors. Note that this
195     * selector is not used for remote repositories which are passed as request parameters to the repository system,
196     * those repositories are supposed to have their authentication (if any) already set.
197     * 
198     * @return The authentication selector to use, never {@code null}.
199     * @see org.eclipse.aether.repository.RemoteRepository#getAuthentication()
200     * @see RepositorySystem#newResolutionRepositories(RepositorySystemSession, java.util.List)
201     */
202    AuthenticationSelector getAuthenticationSelector();
203
204    /**
205     * Gets the registry of artifact types recognized by this session, for instance when processing artifact
206     * descriptors.
207     * 
208     * @return The artifact type registry, never {@code null}.
209     */
210    ArtifactTypeRegistry getArtifactTypeRegistry();
211
212    /**
213     * Gets the dependency traverser to use for building dependency graphs.
214     * 
215     * @return The dependency traverser to use for building dependency graphs or {@code null} if dependencies are
216     *         unconditionally traversed.
217     */
218    DependencyTraverser getDependencyTraverser();
219
220    /**
221     * Gets the dependency manager to use for building dependency graphs.
222     * 
223     * @return The dependency manager to use for building dependency graphs or {@code null} if dependency management is
224     *         not performed.
225     */
226    DependencyManager getDependencyManager();
227
228    /**
229     * Gets the dependency selector to use for building dependency graphs.
230     * 
231     * @return The dependency selector to use for building dependency graphs or {@code null} if dependencies are
232     *         unconditionally included.
233     */
234    DependencySelector getDependencySelector();
235
236    /**
237     * Gets the version filter to use for building dependency graphs.
238     * 
239     * @return The version filter to use for building dependency graphs or {@code null} if versions aren't filtered.
240     */
241    VersionFilter getVersionFilter();
242
243    /**
244     * Gets the dependency graph transformer to use for building dependency graphs.
245     * 
246     * @return The dependency graph transformer to use for building dependency graphs or {@code null} if none.
247     */
248    DependencyGraphTransformer getDependencyGraphTransformer();
249
250    /**
251     * Gets the custom data associated with this session.
252     * 
253     * @return The session data, never {@code null}.
254     */
255    SessionData getData();
256
257    /**
258     * Gets the cache the repository system may use to save data for future reuse during the session.
259     * 
260     * @return The repository cache or {@code null} if none.
261     */
262    RepositoryCache getCache();
263
264    /**
265     * Get the file transformer manager
266     * 
267     * @return the manager, never {@code null}
268     */
269    FileTransformerManager getFileTransformerManager();
270
271}