source: trunk/lib/SVN.h @ 1217

Last change on this file since 1217 was 1217, checked in by Peter Johansson, 11 years ago

update docs and remove third argument in cleanup_failed_init since the bool was not used in function. refs #371

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 8.9 KB
Line 
1#ifndef _theplu_svndigest_svn_
2#define _theplu_svndigest_svn_
3
4// $Id: SVN.h 1217 2010-10-10 00:46:37Z peter $
5
6/*
7  Copyright (C) 2006 Jari Häkkinen
8  Copyright (C) 2007, 2008 Jari Häkkinen, Peter Johansson
9  Copyright (C) 2009 Peter Johansson
10
11  This file is part of svndigest, http://dev.thep.lu.se/svndigest
12
13  svndigest is free software; you can redistribute it and/or modify it
14  under the terms of the GNU General Public License as published by
15  the Free Software Foundation; either version 3 of the License, or
16  (at your option) any later version.
17
18  svndigest is distributed in the hope that it will be useful, but
19  WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21  General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with svndigest. If not, see <http://www.gnu.org/licenses/>.
25*/
26
27// Turning off warnings from using deprecated function, i.e., we are
28// using subversion 1.4
29#ifndef SVN_DEPRECATED
30#define SVN_DEPRECATED
31#endif
32
33
34#include <map>
35#include <stdexcept>
36#include <string>
37#include <vector>
38
39#include <subversion-1/svn_client.h>
40#include <subversion-1/svn_types.h>
41
42namespace theplu {
43namespace svndigest {
44
45  struct log_receiver_baton;
46
47  ///
48  /// If something goes wrong in the use of the different SVN classes,
49  /// an SVNException is thrown.
50  ///
51  struct SVNException : public std::runtime_error
52  { 
53    SVNException(const std::string& msg, svn_error_t* error=NULL);
54
55    virtual ~SVNException(void) throw();
56    /**
57       override base implementation
58     */
59    const char* what(void) const throw();
60
61    /**
62       access svn_error_t
63     */
64    const svn_error_t* error(void) const;
65  private:
66    svn_error_t* error_;
67    std::string msg_;
68  };
69
70  /**
71     \brief The SVN class is a front end to the subversion API.
72
73     SVN provides one single global access point to the underlying
74     subversion API and makes sure that there is only one point of
75     access for the binary.
76
77     The singleton SVN object should be initialized with
78     SVN::instancs(const std::string& path), rather than
79     SVN::instance(void), before using any other subversion related
80     classes or calls. Best practice is to initilize the singleton
81     object early in the main program. The logic behind this
82     requirement is that all subverison related classes and calls
83     expect that repository and WC access is properly set up at
84     initialization. However, most functionality is available
85     irrespectively which instance call is made.
86
87     \see Design Patterns (the singleton pattern). Subversion API
88     documents, SVN::instancs(void), SVN::instancs(const
89     std::string&).
90  */
91  class SVN {
92  public:
93
94    enum vc_status {
95      unversioned=0,
96      uptodate,
97      unresolved
98    };
99
100    /**
101       \brief Call the underlying svn_client_blame3 for \a path with
102       \a receiver and \a baton.
103
104       This function is called from SVNblame to do 'svn blame' on an
105       item. The \a receiver and \a baton is defined in SVNblame and
106       the \a receiver is called by the underlying subversion API for
107       every line in \a path provided it the item is under subversion
108       control. The \a baton is used to communicate anonymous
109       information through the API to the \a receiver. If \a path is a
110       binary object an error is returned, all other errors will
111       generate an SVNException.
112
113       \a path can be either a URL or an WC target.
114
115       \return SVN_NO_ERROR or SVN_ERR_CLIENT_IS_BINARY_FILE, the
116       latter can be used to trigger on binary files. Note that errors
117       return from underlying subversion API must be cleared by the
118       receiver.
119
120       \see Subversion API (svn_error_clear).
121    */
122    svn_error_t * client_blame(const std::string& path,
123                               svn_client_blame_receiver_t receiver,
124                               void *baton);
125
126    /**
127       \brief Same as function above with the extension that revision
128       \a rev can be set.
129     */
130    svn_error_t * client_blame(const std::string& path,
131                               svn_client_blame_receiver_t receiver,
132                               void *baton, svn_revnum_t rev);
133
134    /**
135       \brief Call the underlying svn_client_info for \a path with \a
136       receiver and \a baton.
137
138       This function is called from SVNinfo to do 'svn info' on an
139       item. The \a receiver and \a baton is defined in SVNinfo and
140       the \a receiver is called by the underlying subversion API if
141       \a path is under subversion control. The \a baton is used to
142       communicate anonymous information through the API to the \a
143       receiver.
144
145       \a path can be either a URL or an WC target.
146
147       \see Subversion API documentation, SVNinfo
148    */
149    void client_info(const std::string& path, svn_info_receiver_t receiver,
150                     void *baton);
151
152    /**
153       \a path can be either a URL or an WC target.
154
155       \todo doc
156    */
157    void client_log(const std::string& path, svn_log_message_receiver_t receiver,
158                    void *baton);
159
160    /**
161       \brief Get the subversion properties for \a path.
162
163       The retrieved properties are stored in \a properties. To check
164       whether \a is a binary item use SVNproperty::binary(void).
165
166       \a path can be either a URL or an WC target.
167    */
168    void client_proplist(const std::string& path,
169                         std::map<std::string, std::string>& properties);
170
171    /**
172       \brief Get an instance of SVN.
173
174       The singleton SVN object should be initialized with
175       SVN::instancs(const std::string&) before usage of this
176       function. Best practice is to initilize the singleton object
177       early in the main program. The logic behind this requirement is
178       that subverison related classes and calls may expect that
179       repository and WC access is properly set up at initialization.
180
181       \throw An SVNException if the singleton SVN onject is not
182       already initilized.
183
184       \see SVN::instancs(const std::string&)
185    */
186    static SVN* instance(void);
187
188    /**
189       \brief Get an instance of SVN setup against repository pointed
190       to by \a path.
191
192       The singleton SVN object should be initialized with this
193       instance call before any subversion related classes or calls
194       are made. Best practice is to initilize the singleton object
195       early in the main program. The logic behind this requirement is
196       that subverison related classes and calls may expect that
197       repository and WC access is properly set up at initialization.
198
199       \throw Throws an SVNException if initialization fails in the
200       underlying subversion API calls, or if \a path is a URL.
201    */
202    static SVN* instance(const std::string& path);
203
204    /**
205       \brief Set up a repository access session.
206
207       \throws SVNException if session setup fails, or if a session is
208       already set up (i.e., repository cannot be changed during
209       program lifetime).
210    */
211    //    void setup_ra_session(const std::string& path);
212
213    ///
214    /// @brief Check if entry \a path is under version control
215    ///
216    /// @return True if \a path is under version control, false
217    /// otherwise.
218    ///
219    vc_status version_controlled(const std::string& path);
220
221  private:
222    /**
223       \brief Constructor
224
225       The only way to create an object of SVN type is by calling
226       SVN::instance(const std::string&). \a path must be a WC path,
227       i.e., not a URL.
228    */
229    SVN(const std::string& path);
230
231    ///
232    /// @brief Copy Constructor, not implemented.
233    ///
234    SVN(const SVN&);
235    SVN& operator=(const SVN&);
236
237    ///
238    /// @brief The destructor.
239    ///
240    virtual ~SVN(void);
241
242    /**
243       @brief Free resources when svn API calls fail.
244
245       This function will free \a pool resources and throw an
246       exception holding the \a message. If mute is false, the thrown
247       exception also contains \a err.
248
249       \throw cleanup will throw a SVNException
250
251       @see SVNException
252    */
253    void cleanup(svn_error_t *err, apr_pool_t *pool,
254                 std::string message=std::string(), bool mute=false);
255
256    /**
257       @brief Free resources when failing to reach end of
258       constructor.
259
260       cleanup_failed_init will free all resource acquired in the
261       constructor and throw an SVNException with \a message as the
262       message.
263
264       @see SVNException
265    */
266    void cleanup_failed_init(svn_error_t *err, const std::string& message);
267
268    static SVN* instance_;
269
270    // Subversion API stuff
271
272    /**
273       the url is fech with svn info. The ursl is stored in a
274       url_receiver_baton. The struct is filled in the url_receiver
275       function.
276    */
277    struct root_url_receiver_baton {
278      std::string path;
279    };
280
281    /**
282       url_receiver is the function passed to the underlying
283       subversion API call svn_client_info. This function is called by
284       the subversion API for every item matched by the conditions of
285       the API call.
286
287       \see Subversion API documentation
288    */
289    static svn_error_t*
290    root_url_receiver(void *baton, const char *path, const svn_info_t *info,
291                      apr_pool_t *pool);
292
293    svn_error_t* client_blame_call(const std::string& path,
294                                   svn_client_blame_receiver_t receiver,
295                                   void *baton, svn_opt_revision_t& head);
296
297    svn_wc_adm_access_t* adm_access_;
298    apr_allocator_t* allocator_;
299    svn_client_ctx_t* context_;
300    apr_pool_t* pool_;
301    svn_ra_session_t* ra_session_;
302  };
303
304}} // end of namespace svndigest and namespace theplu
305
306#endif
Note: See TracBrowser for help on using the repository browser.