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