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