Package tigase.xml.db

package tigase.xml.db

This package contains implementation of simple data base stored in XML file.

This data base implementation is very simple but also very handy. It simple because it reads whole data base file into memory to operate on data. It allows to store and retrieve only text or character string data.
Data base is kept in XML file. This gives us a few nice benefits:

• First of all this is hierachical data base so you can organize your data in tree like structures. It looks like a file system directory structure and you also operate on it in very similar way.
• Second it allows you to assign any number of values to one key. They are called data lists.

As a whole data base is kept in memory it is not good for storring large number of data in one file. But it is very fast. It is good especially for storring configuration or data which are similar in their nature to LDAP supporting data bases. You don't have to worry about saving data. Each time you add new item to data base it take care about saving them to permanent storage.

XMLDB is the main data base access class. It allows you to create new data base in given file, open data base from given file, add, delete and retrieve data and data lists. All data or data lists are stored in data base nodes. There are three possible kinds of nodes for each data base:

1. root node - this is top node in each XML hierachy tree. There can be only one root node in data base as there can be only one root element in XML file. The element name for root node can be defined by the user when new data base is created or defualt element name 'root' is used.
2. node1 nodes - these are the first level nodes under root node. There can be any number of nodes on this level. All data added for this data base are added to first level node unless subnode path is given. User can define element name of node1 when new data base is created. If not given default element name 'node' is used.
3. subnodes - node on any deeper level under node1 level. There can be any number of subnodes on any level. Subnodes has always 'node' element name and this can't be changed.

All node1 nodes and subnodes can contains any number of data associated with keys. With some keys there ca be more than one value assigned. Such kind of data are called data lists.
Although element name for subnode can not be defined it is actually not important. Because data base user doesn't use subnode element names. He doesn't even use neiher root node element name nor node1 element name. Data base user uses node name what is quite different from node element name. Let see example below:

<node name='roster'/>

In this example node element name is node and node name is roster.
Data base users (actually developers) use only node names.
If you want to access subnode on some level you need to give full path to this subnode. For example, let's assume we have following data base:

  <;node name='tigase'>
   <node name='server'>
   </node>
   <node name='xmpp'>
   </node>
  </node>

If you need to access 'server' subnode you need to call method with '/tigase/server' as subnode path and for subnode 'xmpp' proper subnode path is of course '/tigase/xmpp'. If you skip subnode path or give null as a parameter you will be accessing data on node1 level. You can not access or save data on root node level.

DBElement class extends tigase.xml.Element. It adds some extra functionality useful for data base operations like searching for some specific nodes, add data entries, remove data, and all other common operations not directly related to pure XML processing. Pure XML processing is of course implemented in tigase.xml.Element. The are also some methods which make it easier to save XML tree from memory to disk file in a form which is easier to read by a human.

DBElementFactory is implementation of factory design pattern required by XML DOM builder to create proper Element instances for tree nodes.

Related Packages

Package	Description
tigase.xml	Simple XML parser implementation.
tigase.xml.annotations

Class	Description
DBElement	DBElement class extends tigase.xml.Element.
DBElementFactory	DBElementFactory is implementation of factory design pattern required by XML DOM builder to create proper Element instances for tree nodes.
NodeExistsException	This exception is thrown when user tries to add subnode with name which already exists in data base.
NodeNotFoundException	Exception is thrown when user tries to access non-existen node on 1st level.
Types	Describe class Types here.
Types.DataType	Describe class DataType here.
XMLDB	XMLDB is the main database access class.
XMLDBException	This is parrent exception for all data base related exceptions.