From a46a795b231b7bc41b8e2de412cbaa143e39489e Mon Sep 17 00:00:00 2001
From: Daniel Hornung <d.hornung@indiscale.com>
Date: Wed, 2 Jun 2021 14:58:30 +0200
Subject: [PATCH] DOC WIP: Structure documentation.
---
src/doc/conf.py | 4 ++
src/doc/development/benchmarking.md | 4 ++
src/doc/development/structure.rst | 67 ++++++++++++++++++++++++++++-
3 files changed, 74 insertions(+), 1 deletion(-)
diff --git a/src/doc/conf.py b/src/doc/conf.py
index 7b6ac359..fee036d0 100644
--- a/src/doc/conf.py
+++ b/src/doc/conf.py
@@ -190,6 +190,10 @@ epub_exclude_files = ['search.html']
# '<namespace_here>' : ('<base_url_here>', 'javadoc'),
# }
+javadoc_url_map = {
+ 'org.restlet': ('https://javadocs.restlet.talend.com/2.4/jse/api', 'javadoc'),
+}
+
# -- Options for intersphinx -------------------------------------------------
diff --git a/src/doc/development/benchmarking.md b/src/doc/development/benchmarking.md
index e69de29b..0be78145 100644
--- a/src/doc/development/benchmarking.md
+++ b/src/doc/development/benchmarking.md
@@ -0,0 +1,4 @@
+# Benchmarking CaosDB #
+
+Please refer to the file `doc/devel/Benchmarking.md` in the CaosDB sources for developer resources
+how to do benchmarking and profiling of CaosDB.
diff --git a/src/doc/development/structure.rst b/src/doc/development/structure.rst
index 7117a53f..03950db9 100644
--- a/src/doc/development/structure.rst
+++ b/src/doc/development/structure.rst
@@ -1,4 +1,69 @@
-CaosDB's internal structure
+CaosDB's Internal Structure
===========================
+The CaosDB server
+
+- builds upon the `Restlet <https://restlet.talend.com/>`_ framework to provide a REST interface to
+ the network. See the :ref:`HTTP Resources` section for more information.
+- uses an SQL database (MariaDB or MySQL) as the backend for data storage. This is documented in
+ the :ref:`MySQL Backend` section.
+- has an internal scheduling framework to organize the required backend jobs. Read more on this in
+ the :ref:`Transactions and Schedules<transactions>` section.
+- may use a number of authentication providers. Documentation for this is still to come.
+
+.. _HTTP Resources:
+
+HTTP Resources
+--------------
+
+HTTP resources are implemented in the :java:ref:`resource<org.caosdb.server.resource>` package, in
+classes inheriting from :java:ref:`AbstractCaosDBServerResource` (which inherits Restlet's
+:java:ref:`Resource<org.restlet.resource.Resource>` class). The main :java:ref:`CaosDBServer` class
+defines which HTTP resource (for example ``/Entity/{specifier}``) will be handled by which class
+(:java:ref:`EntityResource` in this case).
+
+Implementing classes need to overwrite for example the ``httpGetInChildClass()`` method (or methods
+corresponding to other HTTP request methods such as POST, PUT, ...). Typically, they might call the
+``execute()`` method of a :java:ref:`Transaction<org.caosdb.server.transaction.Transaction>` object.
+Transactions are explained in detail in the :ref:`Transactions and Schedules<transactions>` section.
+
+.. uml::
+
+ @startuml
+ abstract AbstractCaosDBServerResource
+ class RetrieveEntityResource
+ class EntityResource
+ AbstractCaosDBServerResource <|-- RetrieveEntityResource
+ RetrieveEntityResource <|-- EntityResource
+ @enduml
+
+.. _MySQL Backend:
+
+MySQL Backend
+-------------
+
+The MySQL backend in CaosDB may be substituted by backends for, but at the time of writing this
+documentation, only MySQL (MariaDB is used for testing) is implemented. There are the following
+main packages which handle the backend:
+
+:java:ref:`backend.interfaces<interfaces>`
+ Interfaces which backends may implement. The main method for most interfaces is
+ ``execute(...)`` with arguments depending on the specific interface, and benchmarking methods
+ (``getBenchmark()`` and ``setTransactionBenchmark(b)`` may also be required.
+
+:java:ref:`backend.implementation.MySQL<MySQL>`
+ MySQL implementations of the interfaces. Typical "simple" implementations create a prepared SQL
+ statement from the arguments to ``execute(...)`` and send it to the SQL server.
+
+:java:ref:`backend.transaction<backend.transaction>` classes
+ Subclasses of the abstract :java:ref:`BackendTransaction` which implement the ``execute()``
+ method. These classes may use specific backend implementations (like for example the MySQL
+ implementations) to interact with the backend database.
+
+.. _transactions:
+
+Transactions and Schedules
+--------------------------
+
+
--
GitLab