Changeset 318 for trunk/lib/SVN.h


Ignore:
Timestamp:
May 18, 2007, 11:35:45 AM (14 years ago)
Author:
Jari Häkkinen
Message:

Fixes #167 and addresses #74. Interfaces have changed. SVN::instance usage has changed, read SVN class documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/lib/SVN.h

    r271 r318  
    4646  { inline SVNException(const std::string& msg) : runtime_error(msg) {} };
    4747
    48   ///
    49   /// The SVN class is a front end to the subversion API.
    50   ///
    51   /// SVN provides one single global access point to the underlying
    52   /// subversion API and makes sure that there is only one point of
    53   /// access for the binary.
    54   ///
    55   /// @see Design Patterns (the singleton pattern). Subversion API
    56   /// documents.
    57   ///
     48  /**
     49     \brief The SVN class is a front end to the subversion API.
     50
     51     SVN provides one single global access point to the underlying
     52     subversion API and makes sure that there is only one point of
     53     access for the binary.
     54
     55     The singleton SVN object should be initialized with
     56     SVN::instancs(const std::string& path), rather than
     57     SVN::instance(void), before using any other subversion related
     58     classes or calls. Best practice is to initilize the singleton
     59     object early in the main program. The logic behind this
     60     requirement is that all subverison related classes and calls
     61     expect that repository and WC access is properly set up at
     62     initialization. However, most functionality is available
     63     irrespectively which instance call is made.
     64
     65     \see Design Patterns (the singleton pattern). Subversion API
     66     documents, SVN::instancs(void), SVN::instancs(const
     67     std::string&).
     68  */
    5869  class SVN {
    5970  public:
     
    6576    };
    6677
    67     ///
    68     /// @brief Call the underlying svn_client_blame3 for \a path with
    69     /// \a receiver and \a baton.
    70     ///
    71     /// This function is called from SVNblame to do 'svn blame' on an
    72     /// item. The \a receiver and \a baton is defined in SVNblame and
    73     /// the \a receiver is called by the underlying subversion API for
    74     /// every line in \a path provided it the item is under subversion
    75     /// control. The \a baton is used to communicate anonymous
    76     /// information through the API to the \a receiver. If \a path is
    77     /// a binary object an error is returned, all other errors will
    78     /// generate an SVNException.
    79     ///
    80     /// @return SVN_NO_ERROR or SVN_ERR_CLIENT_IS_BINARY_FILE, the
    81     /// latter can be used to trigger on binary files. Note that
    82     /// errors return from underlying subversion API must be cleared
    83     /// by the receiver.
    84     ///
    85     /// @see Subversion API (svn_error_clear).
    86     ///
     78    /**
     79       \brief Call the underlying svn_client_blame3 for \a path with
     80       \a receiver and \a baton.
     81
     82       This function is called from SVNblame to do 'svn blame' on an
     83       item. The \a receiver and \a baton is defined in SVNblame and
     84       the \a receiver is called by the underlying subversion API for
     85       every line in \a path provided it the item is under subversion
     86       control. The \a baton is used to communicate anonymous
     87       information through the API to the \a receiver. If \a path is a
     88       binary object an error is returned, all other errors will
     89       generate an SVNException.
     90
     91       \a path can be either a URL or an WC target.
     92
     93       \return SVN_NO_ERROR or SVN_ERR_CLIENT_IS_BINARY_FILE, the
     94       latter can be used to trigger on binary files. Note that errors
     95       return from underlying subversion API must be cleared by the
     96       receiver.
     97
     98       \see Subversion API (svn_error_clear).
     99    */
    87100    svn_error_t * client_blame(const std::string& path,
    88101                               svn_client_blame_receiver_t receiver,
    89102                               void *baton);
    90103
    91     ///
    92     /// @brief Call the underlying svn_client_info for \a path with \a
    93     /// receiver and \a baton.
    94     ///
    95     /// This function is called from SVNinfo to do 'svn info' on an
    96     /// item. The \a receiver and \a baton is defined in SVNinfo and
    97     /// the \a receiver is called by the underlying subversion API if
    98     /// \a path is under subversion control. The \a baton is used to
    99     /// communicate anonymous information through the API to the
    100     /// \a receiver.
    101     ///
    102     /// @see Subversion API documentation, SVNinfo
    103     ///
     104    /**
     105       \brief Call the underlying svn_client_info for \a path with \a
     106       receiver and \a baton.
     107
     108       This function is called from SVNinfo to do 'svn info' on an
     109       item. The \a receiver and \a baton is defined in SVNinfo and
     110       the \a receiver is called by the underlying subversion API if
     111       \a path is under subversion control. The \a baton is used to
     112       communicate anonymous information through the API to the \a
     113       receiver.
     114
     115       \a path can be either a URL or an WC target.
     116
     117       \see Subversion API documentation, SVNinfo
     118    */
    104119    void client_info(const std::string& path, svn_info_receiver_t receiver,
    105120                     void *baton);
    106121
    107122    /**
     123       \a path can be either a URL or an WC target.
     124
    108125       \todo doc
    109126    */
    110     void client_log(std::string path, log_receiver_baton* lb);
    111 
    112 
    113     /**
    114        @brief Get the properties for \a path.
     127    void client_log(const std::string& path, svn_log_message_receiver_t receiver,
     128                    void *baton);
     129
     130    /**
     131       \brief Get the subversion properties for \a path.
    115132
    116133       The retrieved properties are stored in \a properties. To check
    117134       whether \a is a binary item use SVNproperty::binary(void).
     135
     136       \a path can be either a URL or an WC target.
    118137    */
    119138    void client_proplist(const std::string& path,
    120139                         std::map<std::string, std::string>& properties);
    121140
    122     ///
    123     /// @brief Get revision dates.
    124     ///
    125     /// Get dates for all commits to the repository. \a root can be a
    126     /// repository path or a path within a working copy. In the latter
    127     /// case the corresponding repository will be used to retrieve
    128     /// commit dates.
    129     ///
    130     /// @return Revision dates in a vector where revision is
    131     /// implicitly defined by vector index, i.e., element 56 in the
    132     /// resulting vector implies revision 56.
    133     ///
    134     /// @note Currently revision 0 (repositoy creation) is not
    135     /// supported.
    136     ///
    137     /// @throw Various error messages generated from the subversion
    138     /// API.
    139     ///
    140     //std::vector<std::string> commit_dates(const std::string& path);
    141 
    142     ///
    143     /// @brief Get an instance of SVN.
    144     ///
    145     /// @throw Throws an SVNException if initialization fails in the
    146     /// underlying subversion API calls.
    147     ///
    148     static SVN* instance(void)
    149     { if (!instance_) instance_=new SVN; return instance_; }
    150 
    151     ///
    152     /// @throws SVNException if session setup fails.
    153     ///
    154     void setup_ra_session(const std::string& path);
    155 
    156     ///
    157     /// @throws SVNException if access setup fails.
    158     ///
    159     void setup_wc_adm_access(const std::string& path);
     141    /**
     142       \brief Get an instance of SVN.
     143
     144       The singleton SVN object should be initialized with
     145       SVN::instancs(const std::string&) before usage of this
     146       function. Best practice is to initilize the singleton object
     147       early in the main program. The logic behind this requirement is
     148       that subverison related classes and calls may expect that
     149       repository and WC access is properly set up at initialization.
     150
     151       \throw An SVNException if the singleton SVN onject is not
     152       already initilized.
     153
     154       \see SVN::instancs(const std::string&)
     155    */
     156    static SVN* instance(void);
     157
     158    /**
     159       \brief Get an instance of SVN setup against repository pointed
     160       to by \a path.
     161
     162       The singleton SVN object should be initialized with this
     163       instance call before any subversion related classes or calls
     164       are made. Best practice is to initilize the singleton object
     165       early in the main program. The logic behind this requirement is
     166       that subverison related classes and calls may expect that
     167       repository and WC access is properly set up at initialization.
     168
     169       \throw Throws an SVNException if initialization fails in the
     170       underlying subversion API calls, or if \a path is a URL.
     171    */
     172    static SVN* instance(const std::string& path);
     173
     174    /**
     175       \brief Set up a repository access session.
     176
     177       \throws SVNException if session setup fails, or if a session is
     178       already set up (i.e., repository cannot be changed during
     179       program lifetime).
     180    */
     181    //    void setup_ra_session(const std::string& path);
    160182
    161183    ///
     
    168190
    169191  private:
    170     ///
    171     /// @brief Constructor
    172     ///
    173     /// The only way to create a object of SVN type is by calling
    174     /// SVN::instance.
    175     ///
    176     SVN(void);
     192    /**
     193       \brief Constructor
     194
     195       The only way to create an object of SVN type is by calling
     196       SVN::instance(const std::string&). \a path must be a WC path,
     197       i.e., not a URL.
     198    */
     199    SVN(const std::string& path);
    177200
    178201    ///
     
    218241    // Subversion API stuff
    219242
    220     static svn_error_t *
    221     log_message_receiver(void *baton, apr_hash_t *changed_paths,
    222                          svn_revnum_t rev, const char *author, const char *date,
    223                          const char *msg, apr_pool_t *pool);
     243    /**
     244       the url is fech with svn info. The ursl is stored in a
     245       url_receiver_baton. The struct is filled in the url_receiver
     246       function.
     247    */
     248    struct root_url_receiver_baton {
     249      std::string path;
     250    };
     251
     252    /**
     253       url_receiver is the function passed to the underlying
     254       subversion API call svn_client_info. This function is called by
     255       the subversion API for every item matched by the conditions of
     256       the API call.
     257
     258       \see Subversion API documentation
     259    */
     260    static svn_error_t*
     261    root_url_receiver(void *baton, const char *path, const svn_info_t *info,
     262                      apr_pool_t *pool);
    224263
    225264    svn_wc_adm_access_t* adm_access_;
     
    230269  };
    231270
    232     // Log message receiver
    233     struct log_receiver_baton {
    234       std::vector<std::string> authors;
    235       std::vector<std::string> commit_dates;
    236       std::vector<std::string> msg;
    237       std::vector<size_t> rev;
    238     };
    239 
    240271}} // end of namespace svndigest and namespace theplu
    241272
Note: See TracChangeset for help on using the changeset viewer.