XMLDB (Tigase Utils 3.5.1 API)

java.lang.Object
- tigase.xml.db.XMLDB

```
public class XMLDB
extends Object
```
XMLDB is the main database access class. It allows you to create new database in given file, open database from given file, add, delete and retrieve data and data lists. All data or data lists are stored in database nodes. There are three possible kinds of nodes for each database:
1. root node - this is top node in each XML hierachy tree. There can be only one root node in database 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 database 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 database are added to first level node unless subnode path is given. User can define element name of node1 when new database 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 have 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 user database doesn't use subnode element names. He doesn't even use neiher root node element name nor node1 element name. database 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.
database 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 database:
```
  <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.

Created: Tue Oct 26 15:27:33 2004
Author:

Artur Hefczyc

Constructor Summary

Constructors
Constructor and Description

XMLDB(String db_file)
Creates XMLDB object with desired filename, if file modes is enabled then appropriate saver thread is created as well.

Constructors
Constructor and Description
`XMLDB(String db_file)` Creates XMLDB object with desired filename, if file modes is enabled then appropriate saver thread is created as well.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addNode1(String node1_id)` Adds new node
`static XMLDB`	`createDB(String db_file, String root_name, String node1_name)` Factory method creating and setting up XMLDB
`DBElement`	`findNode1(String node1_id)` Return Element corresponding to the node name
`List<String>`	`getAllNode1s()` Retrieve list of nodes
`long`	`getAllNode1sCount()` Retrieve number of nodes
`Object`	`getData(String node1_id, String key)` Retrieve value of given node
`Object`	`getData(String node1_id, String subnode, String key)` Retrieve value of given node under specific path
`Object`	`getData(String node1_id, String subnode, String key, Object def)` Retrieve value of given node under specific path
`double`	`getDataDouble(String node1_id, String subnode, String key, double def)` Retrieve value of given node under specific path
`double[]`	`getDataDoubleList(String node1_id, String subnode, String key)` Retrieve values of given node under specific path
`int`	`getDataInt(String node1_id, String subnode, String key, int def)` Retrieve value of given node under specific path
`int[]`	`getDataIntList(String node1_id, String subnode, String key)` Retrieve values of given node under specific path
`String[]`	`getDataList(String node1_id, String subnode, String key)` Retrieve values of given node under specific path
`String`	`getDBFileName()` Retrieves filename
`String[]`	`getKeys(String node1_id)` Retrieve list of keys under root
`String[]`	`getKeys(String node1_id, String subnode)` Retrieve list of keys under specific path
`protected DBElement`	`getNode(String node1_id, String subnode, boolean auto_create)` Retrieves the node of the given name at specific path
`protected DBElement`	`getNode1(String node1_id)`
`String[]`	`getSubnodes(String node1_id)` Retrieve list of subnodes under root
`String[]`	`getSubnodes(String node1_id, String subnode)` Retrieve list of subnodes under specific path
`protected void`	`loadDB()` Loads XML from file
`void`	`removeData(String node1_id, String key)` Removes data of specific key from node of given name under root element
`void`	`removeData(String node1_id, String subnode, String key)` Removes data of specific key from node of given name under given path
`void`	`removeNode1(String node1_id)` Removes the node
`void`	`removeSubnode(String node1_id, String subnode)` Removes node of given name under given path
`protected void`	`saveDB()` Saves XML to file
`void`	`setData(String node1_id, String key, Object value)` Sets data for the given node at root
`void`	`setData(String node1_id, String subnode, String key, Object value)` Sets data for the given node at given path
`protected void`	`setupNewDB(String db_file, String root_name, String node1_name)` Creates basic Elements of the XMLDB
`void`	`sync()` Performs synchronization with the file
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - XMLDB
```
public XMLDB(String db_file)
      throws IOException,
             XMLDBException
```
    Creates XMLDB object with desired filename, if file modes is enabled then appropriate saver thread is created as well. For filenames starting with "memory://" memory mode (i.e. without writing to disk) is enabled
    
    Parameters:
    
    db_file - indicates path to the file on disk to/from which write/read; if parameter starts with "memory://" then memory mode (without actual file usage) is enabled
    
    Throws:
    
    IOException
    
    XMLDBException
- Method Detail
  - createDB
```
public static XMLDB createDB(String db_file,
                             String root_name,
                             String node1_name)
```
    Factory method creating and setting up XMLDB
    
    Parameters:
    
    db_file - indicates path to the file on disk to/from which write/read; if parameter starts with "memory://" then memory mode (without actual file usage) is enabled
    
    root_name - name of the root element
    
    node1_name - name of the node
    
    Returns:
    
    XMLDB object
  - getDBFileName
```
public String getDBFileName()
```
    Retrieves filename
    
    Returns:
    
    filename
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - setupNewDB
```
protected void setupNewDB(String db_file,
                          String root_name,
                          String node1_name)
```
    Creates basic Elements of the XMLDB
    
    Parameters:
    
    db_file - indicates path to the file on disk to/from which write/read; if parameter starts with "memory://" then memory mode (without actual file usage) is enabled
    
    root_name - name of the root element
    
    node1_name - name of the node
  - loadDB
```
protected void loadDB()
               throws IOException,
                      XMLDBException
```
    Loads XML from file
    
    Throws:
    
    IOException
    
    XMLDBException
  - saveDB
```
protected void saveDB()
```
    Saves XML to file
  - getAllNode1sCount
```
public final long getAllNode1sCount()
```
    Retrieve number of nodes
    
    Returns:
    
    number of nodes
  - getAllNode1s
```
public final List<String> getAllNode1s()
```
    Retrieve list of nodes
    
    Returns:
    
    list of nodes
  - findNode1
```
public final DBElement findNode1(String node1_id)
```
    Return Element corresponding to the node name
    
    Parameters:
    
    node1_id - node name
    
    Returns:
    
    Element corresponding to the node name
  - getNode1
```
protected final DBElement getNode1(String node1_id)
                            throws NodeNotFoundException
```
    Parameters:
    
    node1_id -
    
    Returns:
    
    Throws:
    
    NodeNotFoundException
  - addNode1
```
public void addNode1(String node1_id)
              throws NodeExistsException
```
    Adds new node
    
    Parameters:
    
    node1_id - name of the node to add
    
    Throws:
    
    NodeExistsException
  - removeNode1
```
public void removeNode1(String node1_id)
                 throws NodeNotFoundException
```
    Removes the node
    
    Parameters:
    
    node1_id - name of the node to remove
    
    Throws:
    
    NodeNotFoundException
  - getNode
```
protected final DBElement getNode(String node1_id,
                                  String subnode,
                                  boolean auto_create)
                           throws NodeNotFoundException
```
    Retrieves the node of the given name at specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    auto_create - whether to create path if it's missing
    
    Returns:
    
    Throws:
    
    NodeNotFoundException
  - setData
```
public void setData(String node1_id,
                    String subnode,
                    String key,
                    Object value)
             throws NodeNotFoundException
```
    Sets data for the given node at given path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which save the data
    
    value - actual value to be saved
    
    Throws:
    
    NodeNotFoundException
  - setData
```
public void setData(String node1_id,
                    String key,
                    Object value)
             throws NodeNotFoundException
```
    Sets data for the given node at root
    
    Parameters:
    
    node1_id - name of the node
    
    key - under which save the data
    
    value - actual value to be saved
    
    Throws:
    
    NodeNotFoundException
  - getDataList
```
public String[] getDataList(String node1_id,
                            String subnode,
                            String key)
                     throws NodeNotFoundException
```
    Retrieve values of given node under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which read the data
    
    Returns:
    
    array of Strings
    
    Throws:
    
    NodeNotFoundException
  - getDataIntList
```
public int[] getDataIntList(String node1_id,
                            String subnode,
                            String key)
                     throws NodeNotFoundException
```
    Retrieve values of given node under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which read the data
    
    Returns:
    
    array of Integers
    
    Throws:
    
    NodeNotFoundException
  - getDataDoubleList
```
public double[] getDataDoubleList(String node1_id,
                                  String subnode,
                                  String key)
                           throws NodeNotFoundException
```
    Retrieve values of given node under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which read the data
    
    Returns:
    
    array of Doubles
    
    Throws:
    
    NodeNotFoundException
  - getData
```
public Object getData(String node1_id,
                      String subnode,
                      String key,
                      Object def)
               throws NodeNotFoundException
```
    Retrieve value of given node under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which read the data
    
    def - default value if nothing is stored
    
    Returns:
    
    Object with value
    
    Throws:
    
    NodeNotFoundException
  - getDataInt
```
public int getDataInt(String node1_id,
                      String subnode,
                      String key,
                      int def)
               throws NodeNotFoundException
```
    Retrieve value of given node under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which read the data
    
    def - default value if nothing is stored
    
    Returns:
    
    Integer value
    
    Throws:
    
    NodeNotFoundException
  - getDataDouble
```
public double getDataDouble(String node1_id,
                            String subnode,
                            String key,
                            double def)
                     throws NodeNotFoundException
```
    Retrieve value of given node under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which read the data
    
    def - default value if nothing is stored
    
    Returns:
    
    Double value
    
    Throws:
    
    NodeNotFoundException
  - getData
```
public Object getData(String node1_id,
                      String subnode,
                      String key)
               throws NodeNotFoundException
```
    Retrieve value of given node under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - under which read the data
    
    Returns:
    
    Object value
    
    Throws:
    
    NodeNotFoundException
  - getData
```
public Object getData(String node1_id,
                      String key)
               throws NodeNotFoundException
```
    Retrieve value of given node
    
    Parameters:
    
    node1_id - name of the node
    
    key - under which read the data
    
    Returns:
    
    Double value
    
    Throws:
    
    NodeNotFoundException
  - getSubnodes
```
public String[] getSubnodes(String node1_id,
                            String subnode)
                     throws NodeNotFoundException
```
    Retrieve list of subnodes under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    Returns:
    
    arrays of subnodes names
    
    Throws:
    
    NodeNotFoundException
  - getSubnodes
```
public String[] getSubnodes(String node1_id)
                     throws NodeNotFoundException
```
    Retrieve list of subnodes under root
    
    Parameters:
    
    node1_id - name of the node
    
    Returns:
    
    arrays of subnodes names
    
    Throws:
    
    NodeNotFoundException
  - getKeys
```
public String[] getKeys(String node1_id,
                        String subnode)
                 throws NodeNotFoundException
```
    Retrieve list of keys under specific path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    Returns:
    
    arrays of keys names
    
    Throws:
    
    NodeNotFoundException
  - getKeys
```
public String[] getKeys(String node1_id)
                 throws NodeNotFoundException
```
    Retrieve list of keys under root
    
    Parameters:
    
    node1_id - name of the node
    
    Returns:
    
    arrays of subnodes names
    
    Throws:
    
    NodeNotFoundException
  - removeData
```
public void removeData(String node1_id,
                       String subnode,
                       String key)
                throws NodeNotFoundException
```
    Removes data of specific key from node of given name under given path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    key - name of the key
    
    Throws:
    
    NodeNotFoundException
  - removeData
```
public void removeData(String node1_id,
                       String key)
                throws NodeNotFoundException
```
    Removes data of specific key from node of given name under root element
    
    Parameters:
    
    node1_id - name of the node
    
    key - name of the key
    
    Throws:
    
    NodeNotFoundException
  - removeSubnode
```
public void removeSubnode(String node1_id,
                          String subnode)
                   throws NodeNotFoundException
```
    Removes node of given name under given path
    
    Parameters:
    
    node1_id - name of the node
    
    subnode - path to the node
    
    Throws:
    
    NodeNotFoundException
  - sync
```
public void sync()
          throws IOException
```
    Performs synchronization with the file
    
    Throws:
    
    IOException

Class XMLDB

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XMLDB

Method Detail

createDB

getDBFileName

toString

setupNewDB

loadDB

saveDB

getAllNode1sCount

getAllNode1s

findNode1

getNode1

addNode1

removeNode1

getNode

setData

setData

getDataList

getDataIntList

getDataDoubleList

getData

getDataInt

getDataDouble

getData

getData

getSubnodes

getSubnodes

getKeys

getKeys

removeData

removeData

removeSubnode

sync