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 );
 164    /**
 165     * \short Refresh local raw cache
 166     *
 167     * Will try to download the metadata
 168     *
 169     * In case of falure the metadata remains
 170     * as it was before.
 171     *
 172     * \throws repo::RepoNoUrlException if no urls are available.
 173     * \throws repo::RepoNoAliasException if can't figure an alias
 174     * \throws repo::RepoUnknownTypeException if the metadata is unknown
 175     * \throws repo::RepoException if the repository is invalid
 176     *         (no valid metadata found at any of baseurls)
 177     */
 178    void refreshMetadata( const RepoInfo &info,
 179                          RawMetadataRefreshPolicy policy = RefreshIfNeeded,
 180                          const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 181
 182    /**
 183     * \short Clean local metadata
 184     *
 185     * Empty local metadata.
 186     *
 187     * \throws repo::RepoNoAliasException if can't figure an alias
 188     * \throws Exception on unknown error.
 189     */
 190    void cleanMetadata( const RepoInfo &info,
 191                        const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 192
 193    /**
 194     * \short Status of metadata cache
 195     */
 196     RepoStatus cacheStatus( const RepoInfo &info ) const;
 197
 198    /**
 199     * \short Refresh local cache
 200     *
 201     * Will try to build the cache from local metadata.
 202     *
 203     * If the cache exists it will be overwriten.
 204     *
 205     * \note the local metadata must be valid.
 206     *
 207     * \throws repo::RepoNoAliasException if can't figure
 208     *     an alias to look in cache
 209     * \throws repo::RepoMetadataException if the metadata
 210     *     is not enough to build a cache (empty, incorrect, or
 211     *     refresh needed)
 212     * \throws repo::RepoUnknownTypeException
 213     * \throws parser::ParseException if parser encounters an error.
 214     * \throws Exception on unknown error.
 215     */
 216    void buildCache( const RepoInfo &info,
 217                     CacheBuildPolicy policy = BuildIfNeeded,
 218                     const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 219
 220    /**
 221     * \short clean local cache
 222     *
 223     * Clean the cached version of the metadata
 224     *
 225     * \note the local metadata must be valid.
 226     *
 227     * \throws repo::RepoNoAliasException if can't figure an alias to look in cache
 228     * \throws cache::CacheRecordNotFoundException if the cache could not be
 229     *     cleaned because of repository record not found.
 230     * \throws Exception on unknown error.
 231     */
 232    void cleanCache( const RepoInfo &info,
 233                     const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 234
 235    /**
 236     * \short Whether a repository exists in cache
 237     *
 238     * \param RepoInfo to be checked.
 239     */
 240     bool isCached( const RepoInfo &info ) const;
 241
 242    /**
 243     * \short Create a repository object from the cache data
 244     *
 245     * Creating from cache requires that the repository is
 246     * refreshed (metadata downloaded) and cached
 247     *
 248     * \throws repo::RepoNoAliasException if can't figure an alias to look in cache
 249     * \throw RepoNotCachedException When the source is not cached.
 250     */
 251    Repository createFromCache( const RepoInfo &info,
 252                                const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 253
 254    /**
 255     * \short Create a repository object from raw metadata
 256     *
 257     * Creating from cache requires that the repository is
 258     * refreshed (metadata downloaded)
 259     *
 260     * \throw Exception If there are errors parsing the
 261     * raw metadata
 262     */
 263    Repository createFromMetadata( const RepoInfo &info,
 264                                   const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 265
 266    /**
 267     * \short Probe repo metadata type.
 268     *
 269     * \todo FIXME Should this be private?
 270     */
 271    repo::RepoType probe( const Url &url ) const;
 272
 273
 274    /**
 275     * \short Adds a repository to the list of known repositories.
 276     *
 277     *
 278     *
 279     * \throws repo::RepoAlreadyExistsException If the repo clash some
 280     *         unique attribute like alias
 281     * \throws RepoUnknownType If repository type can't be determined
 282     * \throws RepoException If the access to the url fails (while probing).
 283     * \throws Exception On other errors.
 284     */
 285    void addRepository( const RepoInfo &info,
 286                        const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 287
 288    /**
 289     * \short Adds repositores from a repo file to the list of known repositories.
 290     * \param url Url of the repo file
 291     *
 292     * \throws repo::RepoAlreadyExistsException If the repo clash some
 293     * unique attribute like alias
 294     *
 295     * \throws RepoAlreadyExistsException
 296     * \throws MediaException If the access to the url fails
 297     * \throws ParseException If the file parsing fails
 298     * \throws RepoUnknownType If repository type can't be determined
 299     * \throws RepoException ON other repository related errors
 300     * \throws Exception On other errors.
 301     */
 302     void addRepositories( const Url &url,
 303                          const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 304     /**
 305      * \short Remove the best matching repository from known repos list
 306      *
 307      * \throws RepoNotFoundException If no repo match
 308      */
 309     void removeRepository( const RepoInfo & info,
 310                            const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 311
 312     /**
 313      * \short Modify repository attributes
 314      *
 315      * \throws RepoNotFoundException If no repo match
 316      * \throws ParseException If the file parsing fails
 317      * \throws Exception On other errors.
 318      */
 319     void modifyRepository( const std::string &alias,
 320                            const RepoInfo & newinfo,
 321                            const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 322
 323     /**
 324      * \short Find a matching repository info
 325      *
 326      * \note if multiple repositories incorrectly share the
 327      * same alias, the first one found will be returned.
 328      *
 329      * \param alias Repository alias
 330      * \param progressrcv Progress reporting function
 331      * \return RepoInfo of the found repository
 332      * \throws RepoNotFoundException If no repo match the alias
 333      * \throws ParseException If the file parsing fails
 334      * \throws Exception On other errors.
 335      */
 336     RepoInfo getRepositoryInfo( const std::string &alias,
 337                                 const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 338
 339     /**
 340      * \short Find repository info by URL.
 341      *
 342      * \param url URL to find.
 343      * \param urlview url::ViewOption to influence URL matching.
 344      * \param progressrcv Progress receiver function.
 345      * \return RepoInfo of the found repository.
 346      *
 347      * \note if multpile repositories incorrectly share the
 348      * same URL, the first one found will be returned.
 349      *
 350      * \note the string representation of the URLs are compared.
 351      *       The \a urlview can be used to influence which
 352              parts of the URL are to be compared.
 353      *
 354      * \throws RepoNotFoundException If no repo match
 355      * \throws ParseException If the file parsing fails
 356      * \throws Exception On other errors.
 357      */
 358     RepoInfo getRepositoryInfo( const Url & url,
 359                                 const url::ViewOption & urlview = url::ViewOption::DEFAULTS,
 360                                 const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 361
 362   protected:
 363     RepoStatus rawMetadataStatus( const RepoInfo &info );
 364     RepoStatus cacheStatus( const RepoInfo &info );
 365
 366     /**
 367      * Update timestamp of repository index file for the specified repository \a info.
 368      * Used in \ref checkIfToRefreshMetadata() for repo.refresh.delay feature.
 369      */
 370     void touchIndexFile(const RepoInfo & info);
 371
 372   public:
 373
 374   private:
 375     /** Pointer to implementation */
 376     RWCOW_pointer<Impl> _pimpl;
 377   };
 378   ///////////////////////////////////////////////////////////////////
 379
 380   /** \relates RepoManager Stream output */
 381   std::ostream & operator<<( std::ostream & str, const RepoManager & obj );
 382
 383   /////////////////////////////////////////////////////////////////
 384 } // namespace zypp
 385 ///////////////////////////////////////////////////////////////////
 386 #endif // ZYPP2_REPOMANAGER_H