notes/object-model.txt

   1
   2                      The Subversion Object Model
   3                      ---------------------------
   4
   5 Content
   6 =======
   7
   8  * Context
   9  * Requirements
  10  * The Plan
  11  * Documentation
  12  * Testing
  13  * Drawbacks
  14  * Guidelines
  15  * Object Model Outline
  16  * Notes
  17
  18
  19 Context
  20 =======
  21 One of the points that the Subversion project has historically prided
  22 itself on is the ease with which it interfaces to other languages.
  23 We provide support for bindings in ruby, perl, python, and java, while
  24 third parties develop bindings for C++[1], C#[2], Objective-C[3] and other
  25 languages[4].
  26
  27 Every single one of these sets of bindings uses a different object model,
  28 or none at all.  For instance, the in-tree python bindings are largely
  29 generated by SWIG[5], but we do not provide anything more in the way of a
  30 more "pythonic" object-oriented interface.  Though each of the possible
  31 target languages has different idioms, we can define a common object
  32 model for the underlying libraries which presents the Subversion API
  33 in a unified manner, regardless of the language chosen.  This model
  34 shall hereafter be referred to as the Subversion Object Model (SOM).
  35
  36 Such an object model presents a unified interface for developers in all
  37 bindings languages, and allows for a single, language-agnostic set of
  38 documentation.  Several other projects have successfully implemented such
  39 a model, inclding wxWidgets[6] and MapServer[7].  There have even been
  40 past proposals within Subversion[8], but no real progress has been made.
  41 (The exception is the python c-types bindings[9], which have yet to be merged
  42 to trunk.)
  43
  44
  45 Requirements
  46 ============
  47 Some general requirements for the object model, and the language bindings
  48 which implement it:
  49  * Easy and complete document (see Documentation, below)
  50  * Common tests (see Testing, below)
  51  * Dedicated maintainers
  52  * Thorough coverage of the relevant libraries
  53
  54 (These aren't hard-and-fast requirements, just ideas.)
  55
  56
  57 The Plan
  58 ========
  59 The general plan for implementing this is as follows:
  60  1) Document the entire object model, including all APIs.
  61  2) Create a "reference implementation" preferrably in C++, because it
  62     relatively easy to wrap C code with.  (We may even be able to borrow
  63     code form TortoiseSVN or rapidSVN, depending on licensing.)
  64  3) Create unit tests.
  65  4) Lather, rinse, repeat for other languages.  We may be able to use SWIG
  66     to help generate the code for other languages, or just place the object
  67     model layer on top of the current SWIG bindings.
  68
  69 We could do each of the above steps on a per-library basis, or for the
  70 entire project as a whole.  If done per-library, we may want to do the client
  71 library first, as it is currently the library which most third-party bindings
  72 packages provide the most coverage of.  The first library done would probably
  73 take the longest, due to ramp-up costs in wrapping much of libsvn_subr.
  74
  75
  76 Documentation
  77 =============
  78 One of the benefits of using an common object model across different languages
  79 is that they could share documentation.  Indeed, both of the projects mentioned
  80 above, wxWidgets and MapServer, have generic documentation for their various
  81 interfaces.
  82
  83 One of the problems they face (and we would too) is how to generate those docs.
  84 It is both impractical and unwise to abandon the Doxygen documents currently
  85 in our C header files, but these do not acurately reflect an object model.  We
  86 may be able to use Doxygen's XML output to initially generate some of the
  87 documentation from the C header files, but the object model docs would probably
  88 need to be maintained independently of the C headers.  This may be a lot of
  89 work.
  90
  91 In a perfect world, the documentation should be the place where we specify
  92 what the object model will be, and should be completed *before* any code is
  93 actually written.
  94
  95
  96 Testing
  97 =======
  98 Because each of the bindings would use the same model, it would be reasonable
  99 that they could use the same tests.  Ideally, we could write the tests in some
 100 sort of abstract testing language, which could then get compiled to
 101 language-specific tests.  This would allow "write once, run many" tests,
 102 which could apply to all the bindings surfaces.
 103
 104 Unfortunately, I don't yet know of any such testing language or tool.  Until
 105 such time as one exists, we may want to port existing language-specific tests
 106 to the new object model.
 107
 108
 109 Drawbacks
 110 =========
 111 There are drawbacks to a common object model for the Subversion bindings
 112 languages.  These include:
 113
 114  * Maintenance - Both of code and documentation.
 115     (Hmm, but we already *do* have separate docs, at least for the JavaHL
 116      bindings...)
 117
 118  * Tool support - Some of the automated tools discussed above either don't
 119    work well, or just don't exist.
 120
 121  * Compatibility - Do we drop support for exist bindings in favor of the
 122    object-model based ones?  Is this a "2.0" type of project?
 123
 124
 125 Guidelines
 126 ==========
 127 Some proposed guidelines for translating Subverion's C header files
 128 (subversion/include/svn_*.h) into a wrapper language's object model include:
 129
 130  * C modules define a Java package, Python module, etc.
 131
 132  * Module functions and callbacks should be methods of an
 133    interface/mix-in.
 134
 135  * Batons are opaque data structures, and can be represented as empty
 136    interfaces or callable objects.  Contexts are generally represented
 137    as class state.
 138
 139  * In languages for which it is applicable, returned svn_error_t's
 140    should be declared as thrown exceptions.
 141
 142
 143 Object Model Outline
 144 ====================
 145 A brief description of the proposed object model.  This is *not* a
 146 comprehensive specification, we anticipate that such a spec will be part
 147 of the API documentation.
 148
 149 Modules:
 150  * Client
 151  * RepoAccess
 152  * Repository
 153  * FileSystem
 154  * WorkingCopy
 155
 156
 157 Notes
 158 =====
 159 [1] http://rapidsvn.tigris.org/ is one example.  Others are maintained
 160     independently by TortioseSVN (http://tortoisesvn.tigris.org/), and
 161     probably others.
 162 [2] http://www.softec.st/en/OpenSource/ClrProjects/SubversionSharp/SubversionSharp.html
 163 [3] http://scplugin.tigris.org/ maintains an Objective-C interface layer.
 164 [4] See http://subversion.tigris.org/links.html#bindings for a more complete
 165     list.
 166 [5] http://www.swig.org/
 167 [6] http://www.wxwidgets.org/
 168 [7] http://mapserver.gis.umn.edu/
 169 [8] http://svn.haxx.se/dev/archive-2003-10/0215.shtml
 170 [9] http://svn.collab.net/repos/svn/branches/ctypes-python-bindings/