| |
| The Subversion Object Model |
| --------------------------- |
| |
| Content |
| ======= |
| |
| * Context |
| * Requirements |
| * The Plan |
| * Documentation |
| * Testing |
| * Drawbacks |
| * Guidelines |
| * Object Model Outline |
| * Notes |
| |
| |
| Context |
| ======= |
| One of the points that the Subversion project has historically prided |
| itself on is the ease with which it interfaces to other languages. |
| We provide support for bindings in ruby, perl, python, and java, while |
| third parties develop bindings for C++[1], C#[2], Objective-C[3] and other |
| languages[4]. |
| |
| Every single one of these sets of bindings uses a different object model, |
| or none at all. For instance, the in-tree python bindings are largely |
| generated by SWIG[5], but we do not provide anything more in the way of a |
| more "pythonic" object-oriented interface. Though each of the possible |
| target languages has different idioms, we can define a common object |
| model for the underlying libraries which presents the Subversion API |
| in a unified manner, regardless of the language chosen. This model |
| shall hereafter be referred to as the Subversion Object Model (SOM). |
| |
| Such an object model presents a unified interface for developers in all |
| bindings languages, and allows for a single, language-agnostic set of |
| documentation. Several other projects have successfully implemented such |
| a model, inclding wxWidgets[6] and MapServer[7]. There have even been |
| past proposals within Subversion[8], but no real progress has been made. |
| (The exception is the python c-types bindings[9], which have yet to be merged |
| to trunk.) |
| |
| |
| Requirements |
| ============ |
| Some general requirements for the object model, and the language bindings |
| which implement it: |
| * Easy and complete document (see Documentation, below) |
| * Common tests (see Testing, below) |
| * Dedicated maintainers |
| * Thorough coverage of the relevant libraries |
| |
| (These aren't hard-and-fast requirements, just ideas.) |
| |
| |
| The Plan |
| ======== |
| The general plan for implementing this is as follows: |
| 1) Document the entire object model, including all APIs. |
| 2) Create a "reference implementation" preferrably in C++, because it |
| relatively easy to wrap C code with. (We may even be able to borrow |
| code form TortoiseSVN or rapidSVN, depending on licensing.) |
| 3) Create unit tests. |
| 4) Lather, rinse, repeat for other languages. We may be able to use SWIG |
| to help generate the code for other languages, or just place the object |
| model layer on top of the current SWIG bindings. |
| |
| We could do each of the above steps on a per-library basis, or for the |
| entire project as a whole. If done per-library, we may want to do the client |
| library first, as it is currently the library which most third-party bindings |
| packages provide the most coverage of. The first library done would probably |
| take the longest, due to ramp-up costs in wrapping much of libsvn_subr. |
| |
| |
| Documentation |
| ============= |
| One of the benefits of using an common object model across different languages |
| is that they could share documentation. Indeed, both of the projects mentioned |
| above, wxWidgets and MapServer, have generic documentation for their various |
| interfaces. |
| |
| One of the problems they face (and we would too) is how to generate those docs. |
| It is both impractical and unwise to abandon the Doxygen documents currently |
| in our C header files, but these do not acurately reflect an object model. We |
| may be able to use Doxygen's XML output to initially generate some of the |
| documentation from the C header files, but the object model docs would probably |
| need to be maintained independently of the C headers. This may be a lot of |
| work. |
| |
| In a perfect world, the documentation should be the place where we specify |
| what the object model will be, and should be completed *before* any code is |
| actually written. |
| |
| |
| Testing |
| ======= |
| Because each of the bindings would use the same model, it would be reasonable |
| that they could use the same tests. Ideally, we could write the tests in some |
| sort of abstract testing language, which could then get compiled to |
| language-specific tests. This would allow "write once, run many" tests, |
| which could apply to all the bindings surfaces. |
| |
| Unfortunately, I don't yet know of any such testing language or tool. Until |
| such time as one exists, we may want to port existing language-specific tests |
| to the new object model. |
| |
| |
| Drawbacks |
| ========= |
| There are drawbacks to a common object model for the Subversion bindings |
| languages. These include: |
| |
| * Maintenance - Both of code and documentation. |
| (Hmm, but we already *do* have separate docs, at least for the JavaHL |
| bindings...) |
| |
| * Tool support - Some of the automated tools discussed above either don't |
| work well, or just don't exist. |
| |
| * Compatibility - Do we drop support for exist bindings in favor of the |
| object-model based ones? Is this a "2.0" type of project? |
| |
| |
| Guidelines |
| ========== |
| Some proposed guidelines for translating Subversion's C header files |
| (subversion/include/svn_*.h) into a wrapper language's object model include: |
| |
| * C modules define a Java package, Python module, etc. |
| |
| * Module functions and callbacks should be methods of an |
| interface/mix-in. |
| |
| * Batons are opaque data structures, and can be represented as empty |
| interfaces or callable objects. Contexts are generally represented |
| as class state. |
| |
| * In languages for which it is applicable, returned svn_error_t's |
| should be declared as thrown exceptions. |
| |
| |
| Object Model Outline |
| ==================== |
| A brief description of the proposed object model. This is *not* a |
| comprehensive specification, we anticipate that such a spec will be part |
| of the API documentation. |
| |
| Modules: |
| * Client |
| * RepoAccess |
| * Repository |
| * FileSystem |
| * WorkingCopy |
| |
| |
| Notes |
| ===== |
| [1] http://rapidsvn.tigris.org/ is one example. Others are maintained |
| independently by TortioseSVN (http://tortoisesvn.tigris.org/), and |
| probably others. |
| [2] http://www.softec.st/en/OpenSource/ClrProjects/SubversionSharp/SubversionSharp.html |
| [3] http://scplugin.tigris.org/ maintains an Objective-C interface layer. |
| [4] See http://subversion.tigris.org/links.html#bindings for a more complete |
| list. |
| [5] http://www.swig.org/ |
| [6] http://www.wxwidgets.org/ |
| [7] http://mapserver.gis.umn.edu/ |
| [8] http://svn.haxx.se/dev/archive-2003-10/0215.shtml |
| [9] http://svn.apache.org/repos/asf/subversion/branches/ctypes-python-bindings/ |