[evolution-kolab/gnome-2-30] docs: added TextUML model

[Christian Hilberg <chilberg src gnome org>]

commit e3d1614c0f9f1449f34b2893662f3b60c8aa6332
Author: Christian Hilberg <hilberg kernelconcepts de>
Date:   Mon Nov 7 16:06:09 2011 +0100

    docs: added TextUML model
    
    * see README for a discussion of several UML tools and
      why TextUML was chosen
    * added TextUML input files for the main evolution-kolab
      backend classes

 .gitignore                  |    2 +
 docs/uml/README             |   94 +++++++++++++++++++++++++++++++++++++++++++
 docs/uml/addressbook.tuml   |   25 +++++++++++
 docs/uml/calendar.tuml      |   25 +++++++++++
 docs/uml/camel.tuml         |   31 ++++++++++++++
 docs/uml/libekolab.tuml     |   45 ++++++++++++++++++++
 docs/uml/libekolabutil.tuml |    6 +++
 7 files changed, 228 insertions(+), 0 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 3db0f33..29ae274 100644
--- a/.gitignore
+++ b/.gitignore
@@ -60,3 +60,5 @@ test.log
 m4/
 gtk-doc.make
 TODO.tasks
+docs/uml/*.uml
+docs/.metadata
diff --git a/docs/uml/README b/docs/uml/README
new file mode 100644
index 0000000..7c284b6
--- /dev/null
+++ b/docs/uml/README
@@ -0,0 +1,94 @@
+--------------------------------------------------------------------
+
+evolution-kolab - Project UML documentation notes
+
+created:	2011-11-07 Christian Hilberg
+changed:	2011-11-07 Christian Hilberg
+
+--------------------------------------------------------------------
+
+Please note that the primary goal of this UML model is
+visualization of the main class structure (which is implemented
+via GObject in evolution-kolab), and that it may not
+always be possible to maintain a perfect matching between
+UML diagram and GObject implementation. Moreover, the actual
+class API documentation is done via GtkDoc directly from
+the source code and thus not replicated here. The main reason
+for this separately-maintained documentation is that the
+nature of GObject does not allow for automated relationship
+extraction directly from the source code (since there do not
+exist the necessary declarative hints in the C language -
+GtkDoc can only extract the inheritance hierarchy from
+live GObject code, no automatic support for aggregations or
+other associations).
+
+The *.tuml-files are input files of the "TextUML" toolkit
+(see [1]). An Eclipse plugin for editing/visualizing
+is available for free ([2]). The toolkit processes the *.tuml
+files into Eclipse UML models (which can be used from
+there, if needed) and uses graphviz for diagram generation.
+
+Q: Yes, but Eclipse is big and so far away from GNOME!
+So, why not use...
+
+...dia? It is a GTK tool and much closer to GNOME than
+Eclipse is!
+
+A: dia is a very nice tool for drawing graphics, including
+UML diagrams. But it lacks proper support for UML semantics
+and sharing data types and their relationships across multiple
+diagrams (i.e. a true modelling is not really possible).
+This makes maintenance of an UML model a hassle, if it has more
+than a few classes and a single chart.
+
+...ArgoUML? It is cross-platform and everything.
+
+A: ArgoUML uses the XMI file format, which is intended to
+be an XML-based format for UML diagram interchange. While it
+works, it is not truly suited for diagram interchange because
+the format does not specify the visual representation
+of the diagrams. Diffs between XMI files are generally not
+always useful since the object ordering in the file is not
+fixed and may be reordered at any time (the umbrello tool
+likes to do that). This is counter-productive when trying
+to keep the source files under revision control in a
+sensible way.
+
+...bouml? It is powerful and among the best UML tools
+freely available!
+
+A: There are a few issues with bouml, which make it difficult
+to take decision for it:
+- due to a dispute with some Wikipedia admins, the author of
+  bouml ceased active development of bouml
+- there are some efforts to build a stable fork of bouml,
+  namely DoUML, but this project is in a very early state
+  (as of 2011-11), and DoUML will presumably share the same
+  storage issues bouml has (see below)
+- bouml maintains a whole collection of project files even
+  for an empty project. The native file format of bouml is
+  not an interchangeable one
+- bouml implements its own (os-agnostic) access control to
+  (parts of) a project, to provide for collaboratively working
+  on a single project with multiple developers. While this
+  may seem a neat idea, it can be expected to be a source of
+  trouble if the project files themselves are kept under
+  version control
+
+...gaphor? It is GTK and python and all.
+
+A: gaphor (as of 2011-11) is not much mature and elaborated yet,
+it does not support for command line export of diagrams, and has
+a rather weak view on UML modelling (i.e. you can draw everything
+everywhere). While this is nice for a mind-mapping kind of UML usage,
+it is not well suited for documentation.
+
+
+So far, I have not found a more suitable approach than the one
+taken by TextUML, so I am using it. I am, however, always interested
+in getting to know about good and FLOSS UML modelling tools which
+do not get in the way with the FLOSS way of working.
+
+
+[1] http://textuml.sourceforge.net/
+[2] http://marketplace.eclipse.org/content/textuml-toolkit
diff --git a/docs/uml/addressbook.tuml b/docs/uml/addressbook.tuml
new file mode 100644
index 0000000..0d6d08f
--- /dev/null
+++ b/docs/uml/addressbook.tuml
@@ -0,0 +1,25 @@
+package addressbook;
+
+/* EDS classes */
+
+class EBookBackendCache
+end;
+
+class EBookBackendFactory
+end;
+
+class EBookBackend
+end;
+
+/* evolution-kolab classes */
+
+class EBookBackendKolab2Factory specializes EBookBackendFactory
+	aggregation koma_objects	: libekolab::KolabMailAccess;
+end;
+
+class EBookBackendKolab specializes EBookBackend
+	reference book_koma			: libekolab::KolabMailAccess;
+	composition book_cache		: EBookBackendCache;
+end;
+
+end.
diff --git a/docs/uml/calendar.tuml b/docs/uml/calendar.tuml
new file mode 100644
index 0000000..882672f
--- /dev/null
+++ b/docs/uml/calendar.tuml
@@ -0,0 +1,25 @@
+package calendar;
+
+/* EDS classes */
+
+class ECalBackendCache
+end;
+
+class ECalBackendFactory
+end;
+
+class ECalBackend
+end;
+
+/* evolution-kolab classes */
+
+class ECalBackendKolabFactory specializes ECalBackendFactory
+	aggregation koma_objects	: libekolab::KolabMailAccess;
+end;
+
+class ECalBackendKolab specializes ECalBackend
+	reference koma_objects		: libekolab::KolabMailAccess;
+	composition cal_cache		: ECalBackendCache;
+end;
+
+end.
\ No newline at end of file
diff --git a/docs/uml/camel.tuml b/docs/uml/camel.tuml
new file mode 100644
index 0000000..619de0e
--- /dev/null
+++ b/docs/uml/camel.tuml
@@ -0,0 +1,31 @@
+package camel;
+
+/* EDS classes */
+
+class CamelIMAPXProvider
+end;
+
+class CamelIMAPXStore
+end;
+
+class CamelSession
+end;
+
+/* evolution-kolab classes */
+
+class CamelKolabIMAPXMetaDataDb
+end;
+
+class CamelKolabIMAPXMetaData
+end;
+
+class CamelKolabIMAPXProvider specializes CamelIMAPXProvider
+end;
+
+class CamelKolabIMAPXStore specializes CamelIMAPXStore
+end;
+
+class CamelKolabSession specializes CamelSession
+end;
+
+end.
diff --git a/docs/uml/libekolab.tuml b/docs/uml/libekolab.tuml
new file mode 100644
index 0000000..f785149
--- /dev/null
+++ b/docs/uml/libekolab.tuml
@@ -0,0 +1,45 @@
+package libekolab;
+
+class KolabSettingsHandler
+end;
+
+class KolabMailAccess
+	reference ksettings			: KolabSettingsHandler;
+	composition client 			: KolabMailImapClient;
+	composition infodb 			: KolabMailInfoDb;
+	composition mimebuilder		: KolabMailMimeBuilder;
+	composition sidecache		: KolabMailSideCache;
+	composition synchronizer	: KolabMailSynchronizer;
+end;
+
+class KolabMailImapClient
+	reference ksettings			: KolabSettingsHandler;
+	reference mimebuilder		: KolabMailMimeBuilder;
+	composition session			: camel::CamelKolabSession;
+	composition store			: camel::CamelKolabIMAPXStore;	
+end;
+
+class KolabMailInfoDb
+	reference ksettings			: KolabSettingsHandler;
+	composition kdb				: libekolabutil::KolabUtilSqliteDb;	
+end;
+
+class KolabMailMimeBuilder
+	reference ksettings			: KolabSettingsHandler;	
+end;
+
+class KolabMailSideCache
+	reference ksettings			: KolabSettingsHandler;
+	reference mimebuilder		: KolabMailMimeBuilder;
+	composition kdb				: libekolabutil::KolabUtilSqliteDb;	
+end;
+
+class KolabMailSynchronizer
+	reference ksettings			: KolabSettingsHandler;
+	reference client			: KolabMailImapClient;
+	reference infodb			: KolabMailInfoDb;
+	reference sidecache			: KolabMailSideCache;
+	reference mimebuilder		: KolabMailMimeBuilder;
+end;
+
+end.
diff --git a/docs/uml/libekolabutil.tuml b/docs/uml/libekolabutil.tuml
new file mode 100644
index 0000000..c51a8df
--- /dev/null
+++ b/docs/uml/libekolabutil.tuml
@@ -0,0 +1,6 @@
+package libekolabutil;
+
+class KolabUtilSqliteDb
+end;
+
+end.