# 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.