add some doc to service and improve some error handling
authorJosef Reidinger <jreidinger@suse.cz>
Tue, 8 Jul 2008 14:24:48 +0000 (14:24 +0000)
committerJosef Reidinger <jreidinger@suse.cz>
Tue, 8 Jul 2008 14:24:48 +0000 (14:24 +0000)
zypp/RepoManager.cc
zypp/RepoManager.h
zypp/Service.h
zypp/parser/RepoindexFileReader.cc
zypp/parser/RepoindexFileReader.h
zypp/parser/ServiceFileReader.cc
zypp/parser/ServiceFileReader.h

index 29a09e4..3db671f 100644 (file)
@@ -1344,7 +1344,7 @@ namespace zypp
   {
     //check if service isn't already exist
     if( _pimpl->services.find(service)!= _pimpl->services.end() )
-      return; //TODO throw exception
+      return; //FIXME ZYPP_THROW(RepoAlreadyExistsException(service.name()));
 
     //this is need to save location to correct service
     const Service& savedService = *(_pimpl->services.insert( service )).first;
@@ -1383,12 +1383,16 @@ namespace zypp
       filesystem::assert_dir(location.dirname());
 
       std::ofstream file(location.c_str());
+      if( file.fail() )
+        ZYPP_THROW(Exception("failed open file to write"));
 
       for_(it, tmpSet.begin(), tmpSet.end())
       {
         if( it->name() != name )
           it->dumpServiceOn(file);
       }
+
+      MIL << name << " sucessfully deleted from file " << location <<  endl;
     }
 
     //now remove all repositories added by this service
@@ -1458,7 +1462,7 @@ namespace zypp
   {
     //download index file
     media::MediaManager mediamanager;
-    media::MediaAccessId mid = mediamanager.open( service.url() );
+    media::MediaAccessId mid = mediamanager.open( service.url() ); //FIXME check if url is not empty
     mediamanager.attachDesiredMedia( mid );
     mediamanager.provideFile( mid, "repo/repoindex.xml" );
     Pathname path = mediamanager.localPath(mid, "repo/repoindex.xml" );
index b9a18fc..0ebcdff 100644 (file)
@@ -102,7 +102,7 @@ namespace zypp
     typedef ServiceSet::const_iterator ServiceConstIterator;
     typedef ServiceSet::size_type ServiceSizeType;
 
-    //RepoInfo typedefs
+    /** RepoInfo typedefs */
     typedef std::set<RepoInfo> RepoSet;
     typedef RepoSet::const_iterator RepoConstIterator;
     typedef RepoSet::size_type RepoSizeType;
@@ -444,30 +444,98 @@ namespace zypp
                                 const url::ViewOption & urlview = url::ViewOption::DEFAULTS,
                                 const ProgressData::ReceiverFnc & progressrcv = ProgressData::ReceiverFnc() );
 
+    /**
+     * Adds new service by it's name and url
+     *
+     * \param name unique name of service
+     * \param url url to service
+     *
+     * \throws FIXME RepoAlreadyExistException and as reponame is service name
+     */
     void addService( const std::string& name, const Url& url );
+
+    /**
+     * Adds new service
+     *
+     * \param name service info 
+     *
+     * \throws FIXME RepoAlreadyExistException and as reponame is service name
+     */
     void addService( const Service& name );
 
+    /**
+     * Removes service specified by its name
+     *
+     * \param name name of service to remove
+     *
+     * \throws RepoException if service is not found or file with Service cannot be deleted
+     * \throws Exception if file contain more services and rewrite file failed
+     */
     void removeService( const std::string& name );
 
+    /**
+     * Gets true if no service is in RepoManager (so no one in specified location)
+     *
+     * \return true if any Service is in RepoManager
+     */
     bool serviceEmpty() const;
 
+    /**
+     * Gets count of service in RepoManager (in specified location)
+     *
+     * \return count of service
+     */
     ServiceSizeType serviceSize() const;
 
+    /**
+     * Iterator to first service in internal storage.
+     * \note Iterator is immutable, so you cannot change pointed Service
+     * \return Iterator to first service
+     */
     ServiceConstIterator serviceBegin() const;
 
+    /**
+     * Iterator to place behind last service in internal storage.
+     * \return iterator to end
+     */
     ServiceConstIterator serviceEnd() const;
 
+    /**
+     * Finds Service by name or return noService
+     *
+     * \param name unique name of service
+     * \return information about Service
+     */
     Service getService( const std::string& name ) const;
 
+    /**
+     * Refreshs all services
+     * \see refreshService
+     */
     void refreshServices();
 
+    /**
+     * Refresh specific service. 
+     * \throws Exception if cannot download file
+     * \param name service structure
+     */
     void refreshService( const Service& name );
 
     /**
-     * modify service
+     * modify service, rewrite Service to filesystem.
+     * If change Service name, then can escalate to rewrite all repositories which it contain.
+     * 
+     * \param oldName oldName of service
+     * \param service Structure containing new datas
+     *
+     * \throws RepoException if sservice with oldName is not known
+     * \throws Exception if have problems with files
      */
     void modifyService(const std::string& oldName, const Service& service);
 
+    /**
+     * Functor thats filter RepoInfo by service which belongs to.
+     */
     struct MatchServiceName {
       private:
         std::string name;
@@ -477,7 +545,26 @@ namespace zypp
     };
 
     /**
-     * fill to output iterator repositories in service name
+     * fill to output iterator repositories in service name. This output iterator can perform
+     * any action on with Repo or service Container, because it is sets and it isn't dynamic recreate.
+     * \param name service name
+     * \param out output iterator which get all repositories in Service
+     *
+     * example how set priority for each RepoInfo in this service:
+     * \code
+     * //functor
+     * class ChangePriority{
+     *   private:
+     *     int priority;
+     *   public:
+     *     ChangePriority(int prio) : priority(prio) {}
+     *     void doIt( RepoInfo info ) { info.setPriority(priority); }
+     * }
+     *
+     * //somewhere in code
+     * ChangePriority changer(10);
+     * getRepositoriesInService(name,getRepositoriesInService( name, boost::make_function_output_iterator(bind(&ChangePriority::doIt, &changer, _1))));
+     * \endcode
      */ 
 
     template<typename OutputIterator>
index a5def13..b416217 100644 (file)
@@ -34,13 +34,16 @@ namespace zypp
 
         /**
          *  Service with this name.
+         *
+         * \param name unique name of service
          */
         Service( const std::string& name );
 
         /**
-         * Creates service with name and it's url.
-         * Used for adding new services.
-         * \note internal, do not used outside libzypp
+         * Service with name and its URL
+         *
+         * \param name unique name of service
+         * \param url url to service
          */
         Service( const std::string& name, const Url& url );
 
@@ -49,23 +52,58 @@ namespace zypp
         static const Service noService;
 
     public:
+        /**
+         * Gets unique name
+         *
+         * \return name of service
+         */
         std::string name() const;
 
+        /**
+         * Gets url to service
+         *
+         * \return url to service
+         */
         Url url() const;
 
+        /**
+         * Gets from which file is this service loaded or saved.
+         *
+         * \note this is empty for newly created file until it is saved
+         * \return path to file storing this service
+         */
         Pathname location() const;
 
     public:
-
+        
+        /**
+         * Sets file where this service is stored.
+         *
+         * \warning don't use this function, only parses and serializer can
+         *          use it
+         * \param location path where service is stored
+         */
         void setLocation( const Pathname& location );
 
+        /**
+         * Sets url for this service
+         *
+         * \param url url to this service
+         */
         void setUrl( const Url& url );
 
+        /**
+         * Sets name for this service
+         *
+         * \param name new name of this service
+         */
         void setName( const std::string& name );
 
    public:
         /**
          * Writes Service to stream in ".service" format
+         *
+         * \param str stream where serialized version service is written
          */
         void dumpServiceOn( std::ostream & str ) const;
 
index 538c8c2..edcd59a 100644 (file)
@@ -6,7 +6,7 @@
 |                         /_____||_| |_| |_|                           |
 |                                                                      |
 \---------------------------------------------------------------------*/
-/** \file zypp/parser/yum/RepoindexFileReader.cc
+/** \file zypp/parser/RepoindexFileReader.cc
  * Implementation of repoindex.xml file reader.
  */
 #include <iostream>
@@ -14,6 +14,8 @@
 #include "zypp/base/String.h"
 #include "zypp/base/Logger.h"
 
+#include "zypp/RepoInfo.h"
+
 #include "zypp/Pathname.h"
 #include "zypp/parser/xml/Reader.h"
 
index fd18461..46f4f5c 100644 (file)
@@ -6,7 +6,7 @@
 |                         /_____||_| |_| |_|                           |
 |                                                                      |
 \---------------------------------------------------------------------*/
-/** \file zypp/parser/yum/RepoindexFileReader.h
+/** \file zypp/parser/RepoindexFileReader.h
  * Interface of repoindex.xml file reader.
  */
 #ifndef zypp_source_yum_RepoindexFileReader_H
 #include "zypp/base/NonCopyable.h"
 #include "zypp/base/Function.h"
 
-#include "zypp/RepoInfo.h"
-
 namespace zypp
 {
+  class RepoInfo;
+
   namespace parser
   {
 
@@ -28,7 +28,7 @@ namespace zypp
    *
    * After each repository is read, a \ref RepoInfo
    * is prepared and \ref _callback
-   * is called with these two objects passed in.
+   * is called with this object passed in.
    *
    * The \ref _callback is provided on construction.
    *
@@ -44,7 +44,7 @@ namespace zypp
    /**
     * Callback definition.
     * First parameter is a \ref RepoInfo object with the resource
-    * second parameter is the resource type.
+    * FIXME return value is ignored
     */
     typedef function< bool(
         const RepoInfo & )>
@@ -53,13 +53,13 @@ namespace zypp
    /**
     * CTOR. Creates also \ref xml::Reader and starts reading.
     * 
-    * \param repoindex_file is the repoindex.xml file you want to read
+    * \param repoindexFile is the repoindex.xml file you want to read
     * \param callback is a function.
     *
     * \see RepoindexFileReader::ProcessResource
     */
     RepoindexFileReader(
-      const Pathname & repoindex_file, const ProcessResource & callback);
+      const Pathname & repoindexFile, const ProcessResource & callback);
 
     /**
      * DTOR
index e0972a5..0558a29 100644 (file)
@@ -6,7 +6,7 @@
 |                         /_____||_| |_| |_|                           |
 |                                                                      |
 \---------------------------------------------------------------------*/
-/** \file      zypp/repo/RepoFileReader.cc
+/** \file      zypp/parser/RepoFileReader.cc
  *
 */
 #include <iostream>
@@ -40,6 +40,11 @@ namespace zypp
                                   const ProgressData::ReceiverFnc &progress*/ )
     {
       InputStream is(file);
+      if( is.stream().fail() )
+      {
+        ZYPP_THROW(Exception("Failed to open service file"));
+      }
+
       parser::IniDict dict(is);
       for ( parser::IniDict::section_const_iterator its = dict.sectionsBegin();
             its != dict.sectionsEnd();
@@ -63,7 +68,7 @@ namespace zypp
         service.setLocation(file);
         // add it to the list.
         if ( !callback(service) )
-          break;
+          ZYPP_THROW(AbortRequestException());
       }
     }
 
index 137c0fd..b9ddb3c 100644 (file)
@@ -6,7 +6,7 @@
 |                         /_____||_| |_| |_|                           |
 |                                                                      |
 \---------------------------------------------------------------------*/
-/** \file      zypp/repo/ServiceFileReader.h
+/** \file      zypp/parser/ServiceFileReader.h
  *
 */
 #ifndef ZYPP_REPO_SERVICEFILEREADER_H
@@ -28,16 +28,16 @@ namespace zypp
   { /////////////////////////////////////////////////////////////////
 
     /**
-     * \short Read repository data from a .repo file
+     * \short Read service data from a .service file
      *
-     * After each repo is read, a \ref RepoInfo is prepared and \ref _callback
+     * After each service is read, a \ref Service is prepared and \ref _callback
      * is called with the object passed in.
      *
      * The \ref _callback is provided on construction.
      *
      * \code
-     * ServiceFileReader reader(repo_file, 
-     *                bind( &SomeClass::callbackfunc, &SomeClassInstance, _1, _2 ) );
+     * ServiceFileReader reader(service_file, 
+     *                bind( &SomeClass::callbackfunc, &SomeClassInstance, _1 ) );
      * \endcode
      */
     class ServiceFileReader
@@ -47,8 +47,7 @@ namespace zypp
       
      /**
       * Callback definition.
-      * First parameter is a \ref RepoInfo object with the resource
-      * second parameter is the resource type.
+      * First parameter is a \ref Service object with the resource.
       *
       * Return false from the callback to get a \ref AbortRequestException
       * to be thrown and the processing to be cancelled.
@@ -62,17 +61,15 @@ namespace zypp
      /**
       * \short Constructor. Creates the reader and start reading.
       *
-      * \param repo_file A valid .repo file
+      * \param serviceFile A valid .repo file
       * \param callback Callback that will be called for each repository.
-      * \param progress Optional progress function. \see ProgressData
       *
       * \throws AbortRequestException If the callback returns false
       * \throws Exception If a error occurs at reading / parsing
       *
       */
-      ServiceFileReader( const Pathname & repo_file,
-                      const ProcessService & callback/*,
-                      const ProgressData::ReceiverFnc &progress = ProgressData::ReceiverFnc()*/);
+      ServiceFileReader( const Pathname & serviceFile,
+                      const ProcessService & callback);
      
       /**
        * Dtor