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