Let's consider an almost real life example, a simplified situation similar to the EIARD-Infosys project. We have a central gateway located in Bonn, Germany, and two national nodes, say in Italy and France. Each node owns a database containing information on projects concerning Agricultural Research for Development (ARD). We want to allow end-users to search the three databases from a unique site, the German gateway. We also want to phisically leave data on the national nodes.
We can develop such a system installing nodeXML on each node and enabling the gateway to manage XML documents. The latter issue will not be covered in this manual: we only suppose that on the gateway side it is possible to parse and manage XML documents. The first step is to agree for a common structure of XML documents between the gateway and the nodes. We choose two different structures: a first compact document
<PROJECT> <ID>project identifier</ID> <TITLE>Title of the project</TITLE> <SOURCE>Node that owns this project</SOURCE> <PROJECT>and a more complex one
<PROJECT> <ID>project identifier</ID> <TITLE>Title of the project</TITLE> <DESCRIPTION LANGUAGE=''Description language''>Project abstract</DESCRIPTION> <COUNTRY>Project country</COUNTRY> <SOURCE>Node that owns this project</SOURCE> <PROJECT>These two documents will be used to exchange data. The first one will be useful to produce a list of search results, while the second one will be useful to display information about a single project.
Let's concentrate, now, on the node side, where nodeXML will work. Each node's database has a specific structure, different from the other. The italian database is called ProgettiARD and has the following table structure:
| tbl_progetti | |||
| progid | progtitolo | idpaese | descrizione |
| 1 | Agricolando | 5 | In questo progetto... |
| 2 | Zolle | 12 | Siamo qui per... |
| ... | ... | ... | ... |
| tbl_paesi | |
| paeseid | paesenome |
| ... | ... |
| 5 | Senegal |
| ... | ... |
| 12 | Bolivia |
| ... | ... |
A one-to-one relation is estabilished between the two tables by matching of idpaese field in table tbl_progetti with paeseid field of table tbl_paesi, which is a dictionary of country names. Table tbl_progetti will be the main one, as we specify within a config file that we define in the nodexml/config/ directory (see 2) of the italian nodeXML installation:
<nodexmlconfig> <dbtype>mysql</dbtype> <dbname>ProgettiARD</dbname> <dbtable>tbl_progetti</dbtable> <dbprimary>progid</dbprimary> <dbhost>db.italiannode.it</dbhost> <dbuser>antonio</dbuser> <dbpassword>toni1967<dbpassword> <defaultmap>ardprojlist</defaultmap> <condition></condition> </nodexmlconfig>We call this config file infosys. xml. In the nodexml/map/ (see 2) directory we also have to create two map files, one for each structure of XML documents agreed with the gateway. Let's define, then, ardprojlist. xml as follows:
<PROJECT> <ID>progid</ID> <TITLE>progtitolo</TITLE> <SOURCE>%Italy</SOURCE> <PROJECT>In the config file infosys. xml defined above, we set this map as the default one; it links the ID and TITLE elements with the corresponding fields of the main table. As there is no field referring to itself, the national node identity for the source element is specified with a comment, preceded by the percentage (%) character. Let's now define the second map, called ardproj. xml:
<PROJECT> <ID>progid</ID> <TITLE>progtitolo</TITLE> <DESCRIPTION LANGUAGE=''%italian''>descrizione</DESCRIPTION> <COUNTRY>otoo(idpaese,tbl_paesi,paeseid,paesenome)</COUNTRY> <SOURCE>%Italy</SOURCE> <PROJECT>
The COUNTRY element is not contained in the main table and is retrieved from the database using the nodeXML functionality to manage one-to-one database relations. The syntax of the otoo() function is explained in section 4.
We have defined two map files and a config file: the italian node is ready to interact with the central getaway. Let's see the french node database, called ProjetsdelARD:
| tbl_projets | ||
| projid | projtitre | explication |
| 1000 | On irrigue | On est parti et... |
| 2000 | Sauvez les pins | Nous sommes tous labat pour... |
| ... | ... | ... |
| tbl_proj_pays | |
| pp_proj_id | pp_pays_id |
| ... | ... |
| 1000 | 5 |
| 1000 | 27 |
| ... | ... |
| 12 | 15 |
| ... | ... |
| dict_pays | |
| pays_id | pays_nome |
| ... | ... |
| 5 | Senegal |
| 27 | Cameroon |
| ... | ... |
| 15 | Mali |
| ... | ... |
The structure of the French database is very similar to the italian one, but the relation between the main table and the country dictionary is a one-to-many relation. Table pp_proj_pays is used to link, for each project record, as many countries from the dictionary as the number of pairs which have the project identifier in the first field. Let's define the config file and the two maps. We call the config file gateway. xml
<nodexmlconfig> <dbtype>mysql</dbtype> <dbname>ProjetdelARD</dbname> <dbtable>tbl_projets</dbtable> <dbprimary>projid</dbprimary> <dbhost>db.nodefrancais.it</dbhost> <dbuser>Charlotte</dbuser> <dbpassword>liberteegalitefraternite<dbpassword> <defaultmap>ardprojlist</defaultmap> <condition></condition> </nodexmlconfig>
The defaul map, ardprojlist. xml, is:
<PROJECT> <ID>projid</ID> <TITLE>projtitre</TITLE> <SOURCE>%France</SOURCE> <PROJECT>
The second map,ardproj. xml, is:
<PROJECT> <ID>projid</ID> <TITLE>projtitre</TITLE> <DESCRIPTION LANGUAGE=''%french''>explication</DESCRIPTION> <COUNTRY>otom(projid,pp_proj_pays,pp_proj_id,pp_pays_id,dict_pays,pays_id,pays_nome)</COUNTRY> <SOURCE>%France</SOURCE> <PROJECT>
The two maps are very similar to the italian ones, but the french COUNTRY element is linked to the corrisponding results with the one-to-many relation, following the syntax of the otom() function, explained in section 4.
Both nodes have to define aliases for their config files in alias2file; let's suppose infoITA for the italian one and nodeFRA for the french one. Now the two nodes are set up and we can get their information from the central gateway. First, we want to collect a list of all projects. We develop a gateway script like the following:
OUTPUT "<LIST>"
R1 = READ("http://db.italiannode.it/nodexml/nodexml.php?q=select+from+infoITA")
OUTPUT R1
R2 = READ("http://db.nodefrancais.fr/nodexml/nodexml.php?q=select+from+nodeFRA")
OUTPUT R2
OUTPUT "</LIST>"
We used OUTPUT and READ commands as a template for actual functions
of your chosen server side script. Let's suppose that the READ function
cut automatically the NODEXML tags at the beginning and at the end of the
results stream. The script above produces the following output:
<LIST> <PROJECT> <ID>1</ID> <TITLE>Agricolando</TITLE> <SOURCE>Italy</SOURCE> <PROJECT> <PROJECT> <ID>2</ID> <TITLE>Zolle</TITLE> <SOURCE>Italy</SOURCE> <PROJECT> <PROJECT> <ID>1000</ID> <TITLE>On irrigue</TITLE> <SOURCE>France</SOURCE> <PROJECT> <PROJECT> <ID>2000</ID> <TITLE>Sauvez les pins</TITLE> <SOURCE>France</SOURCE> <PROJECT> <LIST>The gateway side script adds an enclosing root element to produce a well-formed XML document. Default maps are used for both nodes. Let's suppose that we want more information on the On irrigue french project. A gateway script to perform this task is the following:
R = READ("http://db.nodefrancais.fr/nodexml/nodexml.php?q=select+ardproj+from+nodeFRA+where+ID=1000")
OUTPUT R
This script produces the following output:
<PROJECT> <ID>1000</ID> <TITLE>On irrigue</TITLE> <DESCRIPTION LANGUAGE="french">On est parti et...</DESCRIPTION> <COUNTRY>Senegal</COUNTRY> <COUNTRY>Cameroon</COUNTRY> <SOURCE>France</SOURCE> <PROJECT>The COUNTRY element is multiple, because it is linked to two database records.