- retrieving attributes, 1st version... does not support translations yet
[platform/upstream/libzypp.git] / zypp / RepoManager.h
1 /*---------------------------------------------------------------------\
2 |                          ____ _   __ __ ___                          |
3 |                         |__  / \ / / . \ . \                         |
4 |                           / / \ V /|  _/  _/                         |
5 |                          / /__ | | | | | |                           |
6 |                         /_____||_| |_| |_|                           |
7 |                                                                      |
8 \---------------------------------------------------------------------*/
9 /** \file       zypp/RepoManager.h
10  *
11 */
12 #ifndef ZYPP_REPOMANAGER_H
13 #define ZYPP_REPOMANAGER_H
14
15 #include <iosfwd>
16 #include <list>
17
18 #include "zypp/base/PtrTypes.h"
19 //#include "zypp/base/ReferenceCounted.h"
20 //#include "zypp/base/NonCopyable.h"
21 #include "zypp/Pathname.h"
22 #include "zypp/ZConfig.h"
23 #include "zypp/Repository.h"
24 #include "zypp/RepoInfo.h"
25 #include "zypp/repo/RepoException.h"
26 #include "zypp/repo/RepoType.h"
27 #include "zypp/RepoStatus.h"
28 #include "zypp/ProgressData.h"
29
30 ///////////////////////////////////////////////////////////////////
31 namespace zypp
32 { /////////////////////////////////////////////////////////////////
33
34    /**
35     * Parses \a repo_file and returns a list of \ref RepoInfo objects
36     * corresponding to repositories found within the file.
37     *
38     * \param repo_file Valid URL of the repo file.
39     * \return found list<RepoInfo>
40     *
41     * \throws MediaException If the access to the url fails
42     * \throws ParseException If the file parsing fails
43     * \throws Exception On other errors.
44     */
45    std::list<RepoInfo> readRepoFile(const Url & repo_file);
46
47   /**
48    * Repo manager settings.
49    * Settings default to ZYpp global settings.
50    */
51   struct RepoManagerOptions
52   {
53     RepoManagerOptions();
54
55     Pathname repoCachePath;
56     Pathname repoRawCachePath;
57     Pathname knownReposPath;
58   };
59
60   /**
61    * \short creates and provides information about known sources.
62    *
63    */
64   class RepoManager
65   {
66     friend std::ostream & operator<<( std::ostream & str, const RepoManager & obj );
67
68   public:
69     /** Implementation  */
70     class Impl;
71
72   public:
73    RepoManager( const RepoManagerOptions &options = RepoManagerOptions() );
74    /** Dtor */
75     ~RepoManager();
76
77     enum RawMetadataRefreshPolicy
78     {
79       RefreshIfNeeded,
80       RefreshForced
81     };
82
83     enum CacheBuildPolicy
84     {
85       BuildIfNeeded,
86       BuildForced
87     };
88
89     enum RepoRemovePolicy
90     {
91
92     };
93
94    /**
95     * \short List known repositories.
96     *
97     * The known repositories are read from
98     * \ref RepoManagerOptions::knownReposPath passed on the Ctor.
99     * Which defaults to ZYpp global settings.
100     * \return found list<RepoInfo>
101     */
102    std::list<RepoInfo> knownRepositories() const;
103
104    /**
105     * \short Status of local metadata
106     */
107     RepoStatus metadataStatus( const RepoInfo &info ) const;
108
109     /**
110      * Checks whether to refresh metadata for specified repository and url.
111      * <p>
112      * The need for refresh is evaluated according to the following conditions,
113      * in that order:
114      * <ul>
115      * <li>the refresh policy (refresh may be forced)
116      * <li>the repo.refresh.delay ZConfig value compared to the difference between
117      *   cached index file timestamp and actual time
118      * <li>the timestamp of cached repo index file compared to the remote
119      *   index file timestamp.
120      * </ul>
121      * <p>
122      * This method checks the status against the specified url only. If more
123      * baseurls are defined for in the RepoInfo, each one must be check
124      * individually. Example:
125      *
126      * <code>
127      *
128      * RepoInfo info;
129      * // try urls one by one
130      * for ( RepoInfo::urls_const_iterator it = info.baseUrlsBegin();
131      *       it != info.baseUrlsEnd(); ++it )
132      * {
133      *   try
134      *   {
135      *     // check whether to refresh metadata
136      *     // if the check fails for this url, it throws, so another url will be checked
137      *     if (!checkIfToRefreshMetadata(info, *it, policy))
138      *       return;
139      *
140      *     // do the actual refresh
141      *   }
142      *   catch (const Exception & e)
143      *   {
144      *     ZYPP_CAUGHT(e);
145      *     ERR << *it << " doesn't look good. Trying another url." << endl;
146      *   }
147      * } // for all urls
148      *
149      * handle("No more URLs.");
150      *
151      * </code>
152      *
153      * \param info
154      * \param url
155      * \param policy
156      * \throws RepoUnknownTypeException
157      * \throws repo::RepoNoAliasException if can't figure an alias
158      * \throws Exception on unknown error
159      *
160      */
161     bool checkIfToRefreshMetadata( const RepoInfo &info,
162                                    const Url &url,
163                                    RawMetadataRefreshPolicy policy = RefreshIfNeeded);
164
165     /**
166      * \short Path where the metadata is downloaded and kept
167      *
168      * Given a repoinfo, tells where \ref RepoManager will download
169      * and keep the raw metadata.
170      *
171      * \param info Repository information
172      *
173      * \throws repo::RepoNoAliasException if can't figure an alias
174      */
175     Pathname metadataPath( const RepoInfo &info ) const;
176
177    /**
178     * \short Refresh local raw cache
179     *
180     * Will try to download the metadata
181     *
182     * In case of falure the metadata remains
183     * as it was before.
184     *
185     * \throws repo::RepoNoUrlException if no urls are available.
186     * \throws repo::RepoNoAliasException if can't figure an alias
187     * \throws repo::RepoUnknownTypeException if the metadata is unknown
188     * \throws repo::RepoException if the repository is invalid
189     *         (no valid metadata found at any of baseurls)
190     */
191    void refreshMetadata( const RepoInfo &info,
192                          RawMetadataRefreshPolicy policy = RefreshIfNeeded,
193                          const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
194
195    /**
196     * \short Clean local metadata
197     *
198     * Empty local metadata.
199     *
200     * \throws repo::RepoNoAliasException if can't figure an alias
201     * \throws Exception on unknown error.
202     */
203    void cleanMetadata( const RepoInfo &info,
204                        const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
205
206    /**
207     * \short Status of metadata cache
208     */
209     RepoStatus cacheStatus( const RepoInfo &info ) const;
210
211    /**
212     * \short Refresh local cache
213     *
214     * Will try to build the cache from local metadata.
215     *
216     * If the cache exists it will be overwriten.
217     *
218     * \note the local metadata must be valid.
219     *
220     * \throws repo::RepoNoAliasException if can't figure
221     *     an alias to look in cache
222     * \throws repo::RepoMetadataException if the metadata
223     *     is not enough to build a cache (empty, incorrect, or
224     *     refresh needed)
225     * \throws repo::RepoUnknownTypeException
226     * \throws parser::ParseException if parser encounters an error.
227     * \throws Exception on unknown error.
228     */
229    void buildCache( const RepoInfo &info,
230                     CacheBuildPolicy policy = BuildIfNeeded,
231                     const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
232
233    /**
234     * \short clean local cache
235     *
236     * Clean the cached version of the metadata
237     *
238     * \note the local metadata must be valid.
239     *
240     * \throws repo::RepoNoAliasException if can't figure an alias to look in cache
241     * \throws cache::CacheRecordNotFoundException if the cache could not be
242     *     cleaned because of repository record not found.
243     * \throws Exception on unknown error.
244     */
245    void cleanCache( const RepoInfo &info,
246                     const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
247
248    /**
249     * \short Whether a repository exists in cache
250     *
251     * \param RepoInfo to be checked.
252     */
253     bool isCached( const RepoInfo &info ) const;
254
255
256     /**
257     * \short Load resolvables into the pool
258     *
259     * Creating from cache requires that the repository is
260     * refreshed (metadata downloaded) and cached
261     *
262     * \throws repo::RepoNoAliasException if can't figure an alias to look in cache
263     * \throw RepoNotCachedException When the source is not cached.
264     */
265    void loadFromCache( const RepoInfo &info,
266                        const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
267    /**
268     * \short Probe repo metadata type.
269     *
270     * \todo FIXME Should this be private?
271     */
272    repo::RepoType probe( const Url &url ) const;
273
274
275    /**
276     * \short Adds a repository to the list of known repositories.
277     *
278     *
279     *
280     * \throws repo::RepoAlreadyExistsException If the repo clash some
281     *         unique attribute like alias
282     * \throws RepoUnknownType If repository type can't be determined
283     * \throws RepoException If the access to the url fails (while probing).
284     * \throws Exception On other errors.
285     */
286    void addRepository( const RepoInfo &info,
287                        const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
288
289    /**
290     * \short Adds repositores from a repo file to the list of known repositories.
291     * \param url Url of the repo file
292     *
293     * \throws repo::RepoAlreadyExistsException If the repo clash some
294     * unique attribute like alias
295     *
296     * \throws RepoAlreadyExistsException
297     * \throws MediaException If the access to the url fails
298     * \throws ParseException If the file parsing fails
299     * \throws RepoUnknownType If repository type can't be determined
300     * \throws RepoException ON other repository related errors
301     * \throws Exception On other errors.
302     */
303     void addRepositories( const Url &url,
304                          const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
305     /**
306      * \short Remove the best matching repository from known repos list
307      *
308      * \throws RepoNotFoundException If no repo match
309      */
310     void removeRepository( const RepoInfo & info,
311                            const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
312
313     /**
314      * \short Modify repository attributes
315      *
316      * \throws RepoNotFoundException If no repo match
317      * \throws ParseException If the file parsing fails
318      * \throws Exception On other errors.
319      */
320     void modifyRepository( const std::string &alias,
321                            const RepoInfo & newinfo,
322                            const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
323
324     /**
325      * \short Find a matching repository info
326      *
327      * \note if multiple repositories incorrectly share the
328      * same alias, the first one found will be returned.
329      *
330      * \param alias Repository alias
331      * \param progressrcv Progress reporting function
332      * \return RepoInfo of the found repository
333      * \throws RepoNotFoundException If no repo match the alias
334      * \throws ParseException If the file parsing fails
335      * \throws Exception On other errors.
336      */
337     RepoInfo getRepositoryInfo( const std::string &alias,
338                                 const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
339
340     /**
341      * \short Find repository info by URL.
342      *
343      * \param url URL to find.
344      * \param urlview url::ViewOption to influence URL matching.
345      * \param progressrcv Progress receiver function.
346      * \return RepoInfo of the found repository.
347      *
348      * \note if multpile repositories incorrectly share the
349      * same URL, the first one found will be returned.
350      *
351      * \note the string representation of the URLs are compared.
352      *       The \a urlview can be used to influence which
353              parts of the URL are to be compared.
354      *
355      * \throws RepoNotFoundException If no repo match
356      * \throws ParseException If the file parsing fails
357      * \throws Exception On other errors.
358      */
359     RepoInfo getRepositoryInfo( const Url & url,
360                                 const url::ViewOption & urlview = url::ViewOption::DEFAULTS,
361                                 const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
362
363   protected:
364     RepoStatus rawMetadataStatus( const RepoInfo &info );
365     void setCacheStatus( const std::string &alias, const RepoStatus &status );
366
367     /**
368      * Update timestamp of repository index file for the specified repository \a info.
369      * Used in \ref checkIfToRefreshMetadata() for repo.refresh.delay feature.
370      */
371     void touchIndexFile(const RepoInfo & info);
372
373   public:
374
375   private:
376     /** Pointer to implementation */
377     RWCOW_pointer<Impl> _pimpl;
378   };
379   ///////////////////////////////////////////////////////////////////
380
381   /** \relates RepoManager Stream output */
382   std::ostream & operator<<( std::ostream & str, const RepoManager & obj );
383
384   /////////////////////////////////////////////////////////////////
385 } // namespace zypp
386 ///////////////////////////////////////////////////////////////////
387 #endif // ZYPP2_REPOMANAGER_H