Revise the intro and the architecture chapters

Author: misdoro

figure-source/queryProcess.odg

@@ -1,13 +1,38 @@
+
+This document describes the implementation and installation of a VAMDC-TAP node using the Java Node Software. It is organized to follow the node development path.
+Each chapter corresponds to an individual development task.
+
+In the :ref:`intro`, a brief description of the components employed in the java node software implementation is given.
+
+:ref:`plugin` chapter presents the architecture of the Java Node Software and gives the details on the interaction interfaces between the node software parts.
+
+Setting up the development environment with the TAPValidator program is described in the :ref:`plugintest` chapter.
+
+The first development task is to access the data in the database. Apache Cayenne library is used to perform this task. The process is briefly described in the
+chapter :ref:`datamodel`.
+Once the access to the data is established, one may proceed to building the XSAMS elements from the database objects, as described in the chapter :ref:`XSAMSGen`.
+The last development task is to define the mapping between the incoming VSS2 queries and the internal database queries. 
+The chapter :ref:`QueryHandling` describes that mapping in detail.
+
+By this moment, node plugin should be capable of producing the XSAMS documents in response to incoming queries.
+Final development task is to implement special queries used to estimate if the database contains data for a given VSS2 request. 
+It is described in the :ref:`metrics` chapter.
+
+The last chapter and last task is to install the node web service (:ref:`deploy`).
+
+
+
 .. _intro:
 
+
 Introduction
 =============
 
 Java implementation of the VAMDC-TAP node software was created in parallel with the Python version to pursue several objectives:
 
 *	Insure that standards are complete and contain no implementation-specific elements
 
-*	Give a choice of the implementation to database maintainers
+*	Give a choice of an implementation to node maintainers
 
 *	Employ the schema-based DOM XML generator to ensure the document validity.
 	It presents an alternative approach to the keywords dictionary as used in Python/Django node software - see below the :ref:`diff` section
@@ -43,14 +68,16 @@ Additional libraries were developed within the VAMDC project are part of Java VA
 	providing object-oriented view on a query string;
 
 * Query mapping library,
-	providing basic support for queries mapping to node database queries using Apache Cayenne objects.
+	providing basic support for mapping of incoming queries to the node database queries using Apache Cayenne objects.
 
 * XSAMS helper library, 
 	providing convenience methods for output XML generator implementation;
 
-* Web application, .war archive integrating all libraries
+* Web application, 
+	.war archive integrating all libraries
 
-* VAMDC-TAP service validation tool, may be used for node software testing
+* TAPValidator,
+	VAMDC-TAP service validation tool that may be used for node plugin testing on all phases of development.
 
 
 Node-specific components
@@ -59,23 +86,17 @@ Node-specific components
 In Java node software each node installation requires creating two libraries:
 
 #. Database Access Objects using Apache Cayenne.
-	This task is well described in the Apache Cayenne documentation [CAYDOC]_ . A fancy graphical tool is provided.
+	This task is well described in the Apache Cayenne documentation [CAYDOC]_ . 
+	A graphical tool is provided allowing to define the database structure and relations.
+	Java classes corresponding to table entities are generated using this tool.
 
 #. Node plugin,
 	A piece of software that implements the node plugin interfaces and integrates with Java VAMDC Node Software application.
 	Node plugin is responsible for a query translation into the database-specific queries and for building the appropriate XSAMS tree
 	from the fetched database access objects.
 
 
-This document is dedicated mostly to describe how to implement and deploy a node plugin.
-
-For the approximate estimation of the required amount of node-specific code, the following numbers should be considered:
 
-*	BASECOL node plugin - total of ~1600 lines of code;
-
-*	KIDA node plugin - total of ~1500 lines of code;
-
-For all nodes those numbers do not include the autogenerated database model classes.
 
 Comparison with the python/django node software
 ----------------------------------------------------
@@ -153,33 +174,30 @@ Node implementation
 
 Implementing a node with the Java Node Software would require the following steps:
 
-*	Create database model and classes, as described in the :ref:`datamodel` section.
+*	The database model and classes should be created, as described in the :ref:`datamodel` section.
 
 	After completing this step you will be able to access your database in a convenient way
 	from any Java software you develop. For the details, see the Apache Cayenne documentation. [CAYDOC]_
 
-*	Set up the project for your plugin, understand the query process and interaction of the node and the plugin.
-	See the :ref:`plugin` section.
-
-*	Create XSAMS tree blocks constructors and builders, as described in the :ref:`XSAMSGen` section
+*	The development environment for the plugin should be deployed. 
+	The query process and the interaction of the node and the plugin should be understood.
+	See the :ref:`plugin` section for the details.
 
-	Here you might need help from the person responsible for database to figure out what XSAMS elements
-	are appropriate for your database content.
+*	XSAMS tree builders should be created, as described in the :ref:`XSAMSGen` section.
+	This work should be performed in collaboration with a person responsible for the scientific content of the
+	database to establish the correspondance of the XSAMS elements and the database content.
 
-	During this step you will be able to test your node plugin: :ref:`plugintest`.
-	Try to eliminate any validation errors.
-	The result would be the same for all queries, but it is normal.
+	At this step the node plugin may be tested according to the procedure described in the section :ref:`plugintest`.
+	XSAMS generation should be verified and all the validation errors should be eliminated at this step.
 
-*	Define the supported restrictables and create mapping classes as described in the :ref:`QueryHandling` section.
+*	The supported restrictables and corresponding mappings should be defined, as described in the :ref:`QueryHandling` section.
 
-	When this step will be accomplished, you are more than half way through the implementation process.
-	You can test different queries and check if you are getting relevant XSAMS documents as the result.
+	Once this step is accomplished, it becomes possible to send different queries to the node.
+	It should be checked if all the produced XSAMS documents are valid against the schema.
 
-*	The last development step would be to implement the query metrics 
-	to be fully compliant with the VAMDC-TAP standard.
-	See the :ref:`metrics` section for the implementation details.
+*	The last development step would be to implement the query metrics that are used to estimate quickly if the node has the data
+	for a particular query or not. See the :ref:`metrics` section for the implementation details.
 
-*	After the node plugin is working, ask your servers manager to deploy the Java Node software 
-	on the application server, as it is described in the :ref:`deploy` section.
-	Test again using the VAMDC-TAP Validator in the network mode.
+*	Once the node plugin is tested and working, it may be deployed on the web server, as described in the :ref:`deploy` section.
+	The node should be tested again with the VAMDC-TAP Validator working in the network mode.
 

source/img/queryProcess.png

@@ -1,54 +1,77 @@
 .. _plugin:
 
-Database plugin
+Node architecture
 =========================
 
+Java implementation of VAMDC-TAP node software is a web-service application implementing a RESTful interface according to VAMDC-TAP standard specification.
+
+It is accessible using the HTTP protocol, with URLs like *http://node.name.tld/vamdc-tap/12_07/VOSI/capabilities* or 
+*http://node.name.tld/vamdc-tap/12_07/TAP/sync?query=select%20species&lang=VSS2&format=XSAMS*.
+Here *http://node.name.tld/vamdc-tap/12_07/* is the node base url, 
+**/VOSI/capabilities** and **/TAP/sync** are endpoint addresses, and
+*?query=select%20species&lang=VSS2&format=XSAMS* are HTTP request parameters.
+
+For the complete list of endpoint addresses implemented please refer to section :ref:`endpoints`.
+
+
 .. _requestflow:
 
 Request processing
 --------------------
 
-In the course of normal operation, node software receives *HTTP GET* and *HTTP HEAD* requests to the */TAP/sync* 
+In the course of normal operation, node software receives *HTTP GET* and *HTTP HEAD* requests to the **/TAP/sync** 
 endpoint and must respond to them with valid XSAMS documents or only response headers respectively. 
 
+The figure below presents a request flow and what components are involved in the request processing.
+
 .. image:: img/queryProcess.png
 
-The following steps are performed to achieve that, Java VAMDC-TAP implementation (**Framework**)
-is responsible for some of them.
-Node **Plugin** is responsible for the others.
-The Apache Cayenne object-relational mapping framework is used to access the **Database**.
+During the request processing the few steps are performed.
+Java VAMDC-TAP implementation (**Framework**) handles the steps that are common for all VAMDC-TAP nodes.
+Node **Plugin** is responsible for the steps that are essentially node-specific.
+To access the **database**, the Apache Cayenne object-relational mapping framework is used.
 
-*	On the query reception, **framework** asks the **plugin** for the list of supported **keywords**.
+*	On the query reception, the **framework** asks the **plugin** for the list of supported **keywords** (Restrictables).
 
-*	**Framework** is parsing the incoming query, checking it's validity and converting it 
-	into a group of easily accessible :ref:`Query` objects.
+*	The **Framework** parses the incoming query. The validity of the query is checked. 
+	A tree of objects is constructed, representing the logical structure of the query.
+	For more details please refer to the :ref:`Query` section.
 
 *	**Framework** asks **Plugin** to construct the document by calling the :ref:`databasePlug` buildXSAMS() method.
 
-*	**Plugin** maps the incoming query to one or more **Database** queries, 
-	as described in the :ref:`QueryMap`.
+*	**Plugin** maps the incoming query logical tree into one or more **Database** queries, 
+	as described in the :ref:`QueryMap` section.
 
-*	Before executing or mapping the queries, **Plugin** *should* check 
-	if the user actually requested the certain branch of XSAMS document to be built.
-	See the :ref:`RequestInterface` checkBranch() method for the details.
-	
-*	**Plugin** receives objects from the **Database**, builds **XSAMS** blocks from them and 
-	gives those blocks to the **Framework**. See the :ref:`XSAMSGen` section for the details.
+*	**Plugin** queries the **database** and retreives **Apache Cayenne** data objects.
+	**XSAMS** elements are built from those data objects and are attached to the XSAMS document tree. 
+	See the :ref:`XSAMSGen` section for the details.
 
 *	When the document tree is built, **Plugin** returns the control to the **Framework**.
 
-*	**Framework** does the final checks on the document tree, calculates accurate metrics for the document.
+*	The **Framework** does the final checks on the document tree and calculates the accurate metrics for the document.
+
+*	The **Framework** converts the document tree into XML stream and sends it to the client.
+
+
+.. _Interfaces:
+Plugin and Framework Interfaces
+---------------------------------
 
-*	**Framework** converts the document tree into XML stream and sends it to the user.
+Interaction between the database plugin and the Java node software is performed through two interfaces:
 
+*	:ref: `DatabasePlug`
+	defined in the **org.vamdc.tapservice.api.DatabasePlug** java interface and implemented by the node developer.
+	Methods of this interface are called by the node software upon the arrival of a VAMDC-TAP request or during the initial startup and operation checks.
 
-Interaction between the database plugin and the Java node software is performed through two compact interfaces.
+*	:ref: `RequestInterface`
+	defined in the **org.vamdc.tapservice.api.RequestInterface** java interface and implemented in the web-service framework.
+	This interface is available to the node plugin to get the request information and feed the XSAMS blocks constructed.
 
 
 .. _DatabasePlug:
 
 DatabasePlugin interface
-------------------------
+++++++++++++++++++++++++++++
 
 Each and every node plugin must implement the **org.vamdc.tapservice.api.DatabasePlug** 
 interface, defining the following methods:
@@ -95,7 +118,7 @@ interface, defining the following methods:
 .. _RequestInterface:
 
 RequestInterface interface
--------------------------------
++++++++++++++++++++++++++++++++
 
 Calls to the node database plugin through :ref:`DatabasePlug` get as a parameter an object
 implementing the **org.vamdc.tapservice.api.RequestInterface**, providing access to the request information and