tigase.xml.db

Class XMLDB

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.

Method Summary

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