Introduction

nodeXML is a prototype of XML database wrapper implemented in a group of php libraries. It addresses the issue of retrieving information located on remote databases (we'll call them nodes) from a central gateway. Data are exchanged as XML documents. Communication between the central gateway and each node is ensured by their mutual knowledge of a previously defined DTD. A DTD (Document Type Definition) defines the structure of a class of XML documents. For example, if we want to represent a message by means of XML, we could think to somethink like

<MESSAGE>
	<FROM>Juan</FROM>
	<TO>Masa</TO>
	<CONTENT>See you tomorrow at 4 p.m.</CONTENT>
</MESSAGE>

The DTD for the class MESSAGE then would be a file that specifies the structure of every MESSAGE document as something beginning with a MESSAGE outer element that contains the three inner elements FROM, TO and CONTEXT. As far as we are concerned, sharing a DTD simply allows both gateway and node to know the element names of the XML files referring to that DTD, so that they can build and read files of the same type. nodeXML doesn't provide any validation facility. The gateway will use element names to specify its search parameters. nodeXML provides a mechanism on the node side to link an XML file structure (eventually referring to a DTD) to the information contained within a database. This mechanism needs a small config file to be edited and relies on map files configuration.

Map files are XML files where each element data is a reference to the database field where information is actually stored. We will use the MESSAGE example again and we suppose that our node has a database table containing a messages archive, which has the following structure:

sender	to	text
Juan	Masa	See you...
Ada	Morgan	Bye bye!
...	...	...

The map file which links this table to the XML file defined above is the following:

<MESSAGE>
	<FROM>sender</FROM>
	<TO>to</TO>
	<CONTENT>text</CONTENT>
</MESSAGE>

Referring to this map, nodeXML builds an XML document with the same structure, replacing field names (sender, to, text) with actual data retrieved from every record within the database table. The result document will be:

<MESSAGE>
	<FROM>Juan</FROM>
	<TO>Masa</TO>
	<CONTENT>See you...</CONTENT>
</MESSAGE>
<MESSAGE>
	<FROM>Ada</FROM>
	<TO>Morgan</TO>
	<CONTENT>Bye, bye!</CONTENT>
</MESSAGE>
...

This is a very simple case; cross-table relations can be expressed too, as we explain below in section 4.

Actually, this is not a well-formed XML document, because the root element couldn't occurr but once. In older versions it was possible to specify a root element from the gateway side: from version 2.2 nodeXML results are always enclosed between the tags NODEXML and \NODEXML

Besides map files configuration, you need to set some values within a config file. It is an XML file like the following:

<nodexmlconfig>
	<dbtype>your_db_type</dbtype>
	<dbname>your_db_name</dbname>
	<dbtable>your_db_table_name</dbtable>
	<dbprimary>your_db_table_index</dbprimary>
	<dbhost>host_where_your_db_is_stored</dbhost>
	<dbuser>your_username_to_access_your_db</dbuser>
	<dbpassword>username_corresponding_password</dbpassword>
	<defaultmap>your_mapfile_name</defaultmap>
	<condition>SQL_condition_to_narrow_your_search</condition>
</nodexmlconfig>

The information of this file is used from nodeXML scripts to estabilish the connection with a database and to choose your local database type. Database types supported are listed in 5. Database type abstraction is obtained using PEAR libraries. dbhost should contain the name of the host where your database is located; if you use odbc as dbtype, then you have to specify your DSN. Element dbtable contains the name of the main table to retrieve data from. The fields specified within the map file are supposed to be contained in this table. The gateway, when quering the node, has to specify a name which is an alias for a config file. Aliases are defined in the file alias2file. This file has the form

name1,file1.xml
name2,file2.xml
...
nameN,fileN.xml

Aliases are used to hide real file names to external users.