diff --git a/src/doc/conf.py b/src/doc/conf.py index 7b6ac359abf8d88d3c60cb37001bc43e00b97872..fee036d0a8a6a090edcdb0025cbc1198406b8f40 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 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0be781453a6f85577dd95f89844fd95f2b4141ba 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 7117a53f84f68a29350e8125e8f3d720724a3360..03950db99b0b5257a55f0ae8285bfe60d35b897a 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 +-------------------------- + +