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