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