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:
- 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.
- 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.
- 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:
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
/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
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.
Class Summary Class Description DBElement
DBElementFactoryis implementation of factory design pattern required by XML DOM builder to create proper
Elementinstances for tree nodes.
TypesDescribe class Types here. XMLDB
XMLDBis the main database access class.
Enum Summary Enum Description Types.DataTypeDescribe class DataType here.
Exception Summary Exception Description NodeExistsExceptionThis exception is thrown when user tries to add subnode with name which already exists in data base. NodeNotFoundExceptionException is thrown when user tries to access non-existen node on 1st level. XMLDBExceptionThis is parrent exception for all data base related exceptions.