Class XMLDB
- java.lang.Object
-
- tigase.xml.db.XMLDB
-
public class XMLDB extends java.lang.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:- 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. - 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. - 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 givenull
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
- 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 '
-
-
Constructor Summary
Constructors Constructor Description XMLDB(java.lang.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 Description void
addNode1(java.lang.String node1_id)
Adds new nodestatic XMLDB
createDB(java.lang.String db_file, java.lang.String root_name, java.lang.String node1_name)
Factory method creating and setting up XMLDBDBElement
findNode1(java.lang.String node1_id)
Return Element corresponding to the node namejava.util.List<java.lang.String>
getAllNode1s()
Retrieve list of nodeslong
getAllNode1sCount()
Retrieve number of nodesjava.lang.Object
getData(java.lang.String node1_id, java.lang.String key)
Retrieve value of given nodejava.lang.Object
getData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
Retrieve value of given node under specific pathjava.lang.Object
getData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, java.lang.Object def)
Retrieve value of given node under specific pathdouble
getDataDouble(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, double def)
Retrieve value of given node under specific pathdouble[]
getDataDoubleList(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
Retrieve values of given node under specific pathint
getDataInt(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, int def)
Retrieve value of given node under specific pathint[]
getDataIntList(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
Retrieve values of given node under specific pathjava.lang.String[]
getDataList(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
Retrieve values of given node under specific pathjava.lang.String
getDBFileName()
Retrieves filenamejava.lang.String[]
getKeys(java.lang.String node1_id)
Retrieve list of keys under rootjava.lang.String[]
getKeys(java.lang.String node1_id, java.lang.String subnode)
Retrieve list of keys under specific pathprotected DBElement
getNode(java.lang.String node1_id, java.lang.String subnode, boolean auto_create)
Retrieves the node of the given name at specific pathprotected DBElement
getNode1(java.lang.String node1_id)
java.lang.String[]
getSubnodes(java.lang.String node1_id)
Retrieve list of subnodes under rootjava.lang.String[]
getSubnodes(java.lang.String node1_id, java.lang.String subnode)
Retrieve list of subnodes under specific pathprotected void
loadDB()
Loads XML from filevoid
removeData(java.lang.String node1_id, java.lang.String key)
Removes data of specific key from node of given name under root elementvoid
removeData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
Removes data of specific key from node of given name under given pathvoid
removeNode1(java.lang.String node1_id)
Removes the nodevoid
removeSubnode(java.lang.String node1_id, java.lang.String subnode)
Removes node of given name under given pathprotected void
saveDB()
Saves XML to filevoid
setData(java.lang.String node1_id, java.lang.String key, java.lang.Object value)
Sets data for the given node at rootvoid
setData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, java.lang.Object value)
Sets data for the given node at given pathprotected void
setupNewDB(java.lang.String db_file, java.lang.String root_name, java.lang.String node1_name)
Creates basic Elements of the XMLDBvoid
sync()
Performs synchronization with the filejava.lang.String
toString()
-
-
-
Constructor Detail
-
XMLDB
public XMLDB(java.lang.String db_file) throws java.io.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:
java.io.IOException
- when the file doesn't existXMLDBException
- when there is a problem with XML DB
-
-
Method Detail
-
createDB
public static XMLDB createDB(java.lang.String db_file, java.lang.String root_name, java.lang.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 enabledroot_name
- name of the root elementnode1_name
- name of the node- Returns:
- XMLDB object
-
getDBFileName
public java.lang.String getDBFileName()
Retrieves filename- Returns:
- filename
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
getAllNode1sCount
public final long getAllNode1sCount()
Retrieve number of nodes- Returns:
- number of nodes
-
getAllNode1s
public final java.util.List<java.lang.String> getAllNode1s()
Retrieve list of nodes- Returns:
- list of nodes
-
findNode1
public final DBElement findNode1(java.lang.String node1_id)
Return Element corresponding to the node name- Parameters:
node1_id
- node name- Returns:
- Element corresponding to the node name
-
addNode1
public void addNode1(java.lang.String node1_id) throws NodeExistsException
Adds new node- Parameters:
node1_id
- name of the node to add- Throws:
NodeExistsException
- when the node already exists
-
removeNode1
public void removeNode1(java.lang.String node1_id) throws NodeNotFoundException
Removes the node- Parameters:
node1_id
- name of the node to remove- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
setData
public void setData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, java.lang.Object value) throws NodeNotFoundException
Sets data for the given node at given path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which save the datavalue
- actual value to be saved- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
setData
public void setData(java.lang.String node1_id, java.lang.String key, java.lang.Object value) throws NodeNotFoundException
Sets data for the given node at root- Parameters:
node1_id
- name of the nodekey
- under which save the datavalue
- actual value to be saved- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getDataList
public java.lang.String[] getDataList(java.lang.String node1_id, java.lang.String subnode, java.lang.String key) throws NodeNotFoundException
Retrieve values of given node under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which read the data- Returns:
- array of Strings
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getDataIntList
public int[] getDataIntList(java.lang.String node1_id, java.lang.String subnode, java.lang.String key) throws NodeNotFoundException
Retrieve values of given node under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which read the data- Returns:
- array of Integers
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getDataDoubleList
public double[] getDataDoubleList(java.lang.String node1_id, java.lang.String subnode, java.lang.String key) throws NodeNotFoundException
Retrieve values of given node under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which read the data- Returns:
- array of Doubles
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getData
public java.lang.Object getData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, java.lang.Object def) throws NodeNotFoundException
Retrieve value of given node under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which read the datadef
- default value if nothing is stored- Returns:
- Object with value
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getDataInt
public int getDataInt(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, int def) throws NodeNotFoundException
Retrieve value of given node under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which read the datadef
- default value if nothing is stored- Returns:
- Integer value
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getDataDouble
public double getDataDouble(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, double def) throws NodeNotFoundException
Retrieve value of given node under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which read the datadef
- default value if nothing is stored- Returns:
- Double value
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getData
public java.lang.Object getData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key) throws NodeNotFoundException
Retrieve value of given node under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- under which read the data- Returns:
- Object value
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getData
public java.lang.Object getData(java.lang.String node1_id, java.lang.String key) throws NodeNotFoundException
Retrieve value of given node- Parameters:
node1_id
- name of the nodekey
- under which read the data- Returns:
- Double value
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getSubnodes
public java.lang.String[] getSubnodes(java.lang.String node1_id, java.lang.String subnode) throws NodeNotFoundException
Retrieve list of subnodes under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the node- Returns:
- arrays of subnodes names
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getSubnodes
public java.lang.String[] getSubnodes(java.lang.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
- when node doesn't exist on first level
-
getKeys
public java.lang.String[] getKeys(java.lang.String node1_id, java.lang.String subnode) throws NodeNotFoundException
Retrieve list of keys under specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the node- Returns:
- arrays of keys names
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
getKeys
public java.lang.String[] getKeys(java.lang.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
- when node doesn't exist on first level
-
removeData
public void removeData(java.lang.String node1_id, java.lang.String subnode, java.lang.String key) throws NodeNotFoundException
Removes data of specific key from node of given name under given path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodekey
- name of the key- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
removeData
public void removeData(java.lang.String node1_id, java.lang.String key) throws NodeNotFoundException
Removes data of specific key from node of given name under root element- Parameters:
node1_id
- name of the nodekey
- name of the key- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
removeSubnode
public void removeSubnode(java.lang.String node1_id, java.lang.String subnode) throws NodeNotFoundException
Removes node of given name under given path- Parameters:
node1_id
- name of the nodesubnode
- path to the node- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
sync
public void sync() throws java.io.IOException
Performs synchronization with the file- Throws:
java.io.IOException
- when the file doesn't exist
-
setupNewDB
protected void setupNewDB(java.lang.String db_file, java.lang.String root_name, java.lang.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 enabledroot_name
- name of the root elementnode1_name
- name of the node
-
loadDB
protected void loadDB() throws java.io.IOException, XMLDBException
Loads XML from file- Throws:
java.io.IOException
- when the file doesn't existXMLDBException
- when root node doesn't exist
-
saveDB
protected void saveDB()
Saves XML to file
-
getNode1
protected final DBElement getNode1(java.lang.String node1_id) throws NodeNotFoundException
- Throws:
NodeNotFoundException
-
getNode
protected final DBElement getNode(java.lang.String node1_id, java.lang.String subnode, boolean auto_create) throws NodeNotFoundException
Retrieves the node of the given name at specific path- Parameters:
node1_id
- name of the nodesubnode
- path to the nodeauto_create
- whether to create path if it's missing- Returns:
- retrieved node
- Throws:
NodeNotFoundException
- when node doesn't exist on first level
-
-