Package tigase.xml.db

Class 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:
    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 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 node
      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
      DBElement findNode1​(java.lang.String node1_id)
      Return Element corresponding to the node name
      java.util.List<java.lang.String> getAllNode1s()
      Retrieve list of nodes
      long getAllNode1sCount()
      Retrieve number of nodes
      java.lang.Object getData​(java.lang.String node1_id, java.lang.String key)
      Retrieve value of given node
      java.lang.Object getData​(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
      Retrieve value of given node under specific path
      java.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 path
      double getDataDouble​(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, double def)
      Retrieve value of given node under specific path
      double[] getDataDoubleList​(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
      Retrieve values of given node under specific path
      int getDataInt​(java.lang.String node1_id, java.lang.String subnode, java.lang.String key, int def)
      Retrieve value of given node under specific path
      int[] getDataIntList​(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
      Retrieve values of given node under specific path
      java.lang.String[] getDataList​(java.lang.String node1_id, java.lang.String subnode, java.lang.String key)
      Retrieve values of given node under specific path
      java.lang.String getDBFileName()
      Retrieves filename
      java.lang.String[] getKeys​(java.lang.String node1_id)
      Retrieve list of keys under root
      java.lang.String[] getKeys​(java.lang.String node1_id, java.lang.String subnode)
      Retrieve list of keys under specific path
      protected DBElement getNode​(java.lang.String node1_id, java.lang.String subnode, boolean auto_create)
      Retrieves the node of the given name at specific path
      protected DBElement getNode1​(java.lang.String node1_id)  
      java.lang.String[] getSubnodes​(java.lang.String node1_id)
      Retrieve list of subnodes under root
      java.lang.String[] getSubnodes​(java.lang.String node1_id, java.lang.String subnode)
      Retrieve list of subnodes under specific path
      protected void loadDB()
      Loads XML from file
      void removeData​(java.lang.String node1_id, java.lang.String key)
      Removes data of specific key from node of given name under root element
      void 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 path
      void removeNode1​(java.lang.String node1_id)
      Removes the node
      void removeSubnode​(java.lang.String node1_id, java.lang.String subnode)
      Removes node of given name under given path
      protected void saveDB()
      Saves XML to file
      void setData​(java.lang.String node1_id, java.lang.String key, java.lang.Object value)
      Sets data for the given node at root
      void 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 path
      protected void setupNewDB​(java.lang.String db_file, java.lang.String root_name, java.lang.String node1_name)
      Creates basic Elements of the XMLDB
      void sync()
      Performs synchronization with the file
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • 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 exist
        XMLDBException - 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 enabled
        root_name - name of the root element
        node1_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 class java.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 node
        subnode - path to the node
        key - under which save the data
        value - 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 node
        key - under which save the data
        value - 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 node
        subnode - path to the node
        key - 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 node
        subnode - path to the node
        key - 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 node
        subnode - path to the node
        key - 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 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 - 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 node
        subnode - path to the node
        key - under which read the data
        def - 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 node
        subnode - path to the node
        key - under which read the data
        def - 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 node
        subnode - path to the node
        key - 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 node
        key - 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 node
        subnode - 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 node
        subnode - 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 node
        subnode - path to the node
        key - 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 node
        key - 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 node
        subnode - 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 enabled
        root_name - name of the root element
        node1_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 exist
        XMLDBException - when root node doesn't exist

      • saveDB

        protected void saveDB()
        Saves XML to file

      • 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 node
        subnode - path to the node
        auto_create - whether to create path if it's missing
        Returns:
        retrieved node
        Throws:
        NodeNotFoundException - when node doesn't exist on first level