From e27ef6829ee4e3d9c20c55e3459cfd518f2f5367 Mon Sep 17 00:00:00 2001 From: hwright Date: Mon, 24 Mar 2008 17:10:34 +0000 Subject: [PATCH] Record some of my long pent up ideas about a generic object model for bindings access to Subversion. This is in no way gospel, and I encourage others to read, comment on, and modify this document. * notes/object-model.txt: Lots of new content. git-svn-id: http://svn.collab.net/repos/svn/trunk@30027 612f8ebc-c883-4be0-9ee0-a4e9ef946e3a --- notes/object-model.txt | 188 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 170 insertions(+), 18 deletions(-) rewrite notes/object-model.txt (80%) diff --git a/notes/object-model.txt b/notes/object-model.txt dissimilarity index 80% index 263a26fff..35a074574 100644 --- a/notes/object-model.txt +++ b/notes/object-model.txt @@ -1,18 +1,170 @@ - - The Subversion Object Model - --------------------------- - -Rules of thumb for translating Subverion's C header files -(subversion/include/svn_*.h) into a wrapper language's object model: - -* 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. + + 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 Subverion'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.collab.net/repos/svn/branches/ctypes-python-bindings/ -- 2.11.4.GIT