notes/object-model.txt

                     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 was the python c-types bindings[9], which existed between
1.6 and 1.14, removed in 1.15)


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/trunk/subversion/bindings/ctypes-python,
before r1936298