Difference between revisions of "XMLConfig"

From GreenVulcano Wiki
Jump to: navigation, search
(Following the XMLConfig public static methods)
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
Class FQN: '''it.greenvulcano.configuration.XMLConfig'''
 
Class FQN: '''it.greenvulcano.configuration.XMLConfig'''
  
==Following the XMLConfig public static methods==
+
==XMLConfig public static methods==
 
<syntaxhighlight lang="java5">
 
<syntaxhighlight lang="java5">
/**
 
* Set the entity resolver used to resolve entities into the configuration
 
* files.
 
*
 
* @param entityResolver
 
*        EntityResolver to use in order to resolve entity. If
 
*        <code>null</code> is specified then the default XML mechanism is
 
*        used.
 
*/
 
public static synchronized void setEntityResolver(EntityResolver entityResolver)
 
 
/**
 
* Use the default entity resolver to resolve entities into the
 
* configuration files. The default entity resolver does not resolve
 
* anything.
 
*
 
* @see #setEntityResolver(org.xml.sax.EntityResolver)
 
*/
 
public static synchronized void setDefaultEntityResolver()
 
 
/**
 
* Return the entity resolver for the configuration.
 
*
 
* @return the entity resolver for the configuration
 
*/
 
public static synchronized EntityResolver getEntityResolver()
 
 
/**
 
* Load a configuration file and, if necessary, notifies registered
 
* listeners. This method can be used in order to preload the configuration
 
* file.
 
*
 
* @param file
 
*        the file to read
 
* @return the complete URL used to load the file.
 
* @exception XMLConfigException
 
*            if error occurs
 
*/
 
public static synchronized URL load(String file) throws XMLConfigException
 
 
/**
 
* Load a configuration file and, if necessary, notifies registered
 
* listeners. This method can be used in order to preload the configuration
 
* file.
 
*
 
* @param file
 
*        the file to read
 
* @param classLoader
 
*        the class loader to use to retrieve the file to read
 
* @param force
 
*        force the reload of file if already present in cache
 
* @param canBeReloaded
 
*        flag that indicates if this file can be changed and can be
 
*        reloaded
 
* @return the complete URL used to load the file.
 
* @exception XMLConfigException
 
*            if error occurs
 
*/
 
public static synchronized URL load(String file, ClassLoader classLoader, boolean force, boolean canBeReloaded)
 
        throws XMLConfigException
 
/**
 
* Discard all cached configuration files, notifies all registered
 
* listeners, reload discarded files and notifies all registered listeners.
 
*
 
* @exception XMLConfigException
 
*            if error occurs
 
*/
 
public static synchronized void reloadAll() throws XMLConfigException
 
 
/**
 
* If loaded discard the given file and notifies all registered listeners,
 
* then reload the given file (only if it was previously loaded) and
 
* notifies all registered listeners.
 
*
 
* @param file
 
*        the file to reload
 
* @exception XMLConfigException
 
*            if error occurs
 
*/
 
public static synchronized void reload(String file) throws XMLConfigException
 
 
/**
 
* Discard all cached files and notifies all listeners.
 
*/
 
public static synchronized void discardAll()
 
 
/**
 
* Discard the given file. If the file was previously loaded then the
 
* listeners will be notified, otherwise no action will be taken.
 
*
 
* @param file
 
*        the file to discard
 
*/
 
public static synchronized void discard(String file)
 
 
/**
 
* Returns an array of String s containing the names of the files
 
* currently loaded into XMLConfig private cache.
 
*
 
* @return an array of String s containing the names of the files
 
*        currently loaded into XMLConfig private cache.
 
*/
 
public static synchronized String[] getLoadedFiles()
 
 
/**
 
* Return the value for a node.
 
*
 
* @param node
 
*        input Node.
 
*
 
* @return the node value. The value for an Element is the concatenation of
 
*        children values. For other nodes the value is
 
*        <code>node.getNodeValue()</code>.
 
*/
 
public static String getNodeValue(Node node)
 
 
/**
 
* Return the value of a NodeList as concatenation of values of all nodes
 
* contained in the list.
 
*
 
* @param node
 
*        the node list
 
* @return the nodes value
 
*/
 
public static String getNodeValue(NodeList node)
 
 
 
/**
 
/**
 
* Reads a value. If the XPath selects many nodes the values are appended
 
* Reads a value. If the XPath selects many nodes the values are appended
Line 139: Line 13:
 
*        file.
 
*        file.
 
*  
 
*  
* @return the searched value or <code>null</code> if the XPath select no
+
* @return the searched value or null if the XPath select no
 
*        node.
 
*        node.
 
*  
 
*  
Line 157: Line 31:
 
*        parameter to read specified as relative path to the node.
 
*        parameter to read specified as relative path to the node.
 
*  
 
*  
* @return the searched value or <code>null</code> if the XPath select no
+
* @return the searched value or null if the XPath selects no node.
*        node.
 
 
*  
 
*  
 
* @throws XMLConfigException
 
* @throws XMLConfigException
Line 179: Line 52:
 
*  
 
*  
 
* @return the searched value or the specified default value if the XPath
 
* @return the searched value or the specified default value if the XPath
*        select no node or an error occurs.
+
*        selects no node or an error occurs.
 
*  
 
*  
 
*/
 
*/
Line 215: Line 88:
 
*        if true the data can be unencrypted
 
*        if true the data can be unencrypted
 
*  
 
*  
* @return the searched value or <code>null</code> if the XPath select no
+
* @return the searched value or null if the XPath select no node.
*        node.
 
 
* @throws XMLConfigException
 
* @throws XMLConfigException
 
*        if some error occurs.
 
*        if some error occurs.
Line 237: Line 109:
 
*        if true the data can be unencrypted
 
*        if true the data can be unencrypted
 
*  
 
*  
* @return the searched value or <code>null</code> if the XPath select no
+
* @return the searched value or null if the XPath selects no node.
*        node.
 
 
*  
 
*  
 
* @throws XMLConfigException
 
* @throws XMLConfigException
Line 300: Line 171:
 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
 
*  
 
*  
* @return the searched value or <code>null</code> if the XPath select no
+
* @return the searched value or null if the XPath select no node.
*        node.
 
 
* @throws XMLConfigException
 
* @throws XMLConfigException
 
*        if some error occurs.
 
*        if some error occurs.
Line 318: Line 188:
 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
 
*  
 
*  
* @return the searched value or <code>null</code> if the XPath select no
+
* @return the searched value or null if the XPath select no node.
*        node.
 
 
*  
 
*  
 
* @throws XMLConfigException
 
* @throws XMLConfigException
Line 391: Line 260:
  
 
/**
 
/**
* Return an integer parameter. <br>
+
* Return an integer parameter.  
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to an integer.
 
* to an integer.
 
*  
 
*  
Line 405: Line 274:
  
 
/**
 
/**
* Return an integer parameter. <br>
+
* Return an integer parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to an integer.
 
* to an integer.
 
*  
 
*  
Line 422: Line 291:
  
 
/**
 
/**
* Return an integer parameter. <br>
+
* Return an integer parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to an integer.
 
* to an integer.
 
*  
 
*  
Line 439: Line 308:
  
 
/**
 
/**
* Return an integer parameter. <br>
+
* Return an integer parameter.  
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to an integer.
 
* to an integer.
 
*  
 
*  
Line 457: Line 326:
  
 
/**
 
/**
* Return a long parameter. <br>
+
* Returns a long parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then converts it
 
* to a long.
 
* to a long.
 
*  
 
*  
Line 471: Line 340:
  
 
/**
 
/**
* Return a long parameter. <br>
+
* Returns a long parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a long.
 
* to a long.
 
*  
 
*  
Line 488: Line 357:
  
 
/**
 
/**
* Return a long parameter. <br>
+
* Returns a long parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a long.
 
* to a long.
 
*  
 
*  
Line 503: Line 372:
  
 
/**
 
/**
* Return a long parameter. <br>
+
* Returns a long parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a long.
 
* to a long.
 
*  
 
*  
Line 520: Line 389:
  
 
/**
 
/**
* Return a double parameter. <br>
+
* Returns a double parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a double.
 
* to a double.
 
*  
 
*  
Line 534: Line 403:
  
 
/**
 
/**
* Return a double parameter. <br>
+
* Returns a double parameter.  
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a double.
 
* to a double.
 
*  
 
*  
Line 551: Line 420:
  
 
/**
 
/**
* Return a double parameter. <br>
+
* Return a double parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a double.
 
* to a double.
 
*  
 
*  
Line 566: Line 435:
  
 
/**
 
/**
* Return a double parameter. <br>
+
* Returns a double parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a double.
 
* to a double.
 
*  
 
*  
Line 584: Line 453:
  
 
/**
 
/**
* Return a float parameter. <br>
+
* Returns a float parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then convert it
 
* to a float.
 
* to a float.
 
*  
 
*  
Line 598: Line 467:
  
 
/**
 
/**
* Return a float parameter. <br>
+
* Return a float parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then converts it
 
* to a float.
 
* to a float.
 
*  
 
*  
Line 615: Line 484:
  
 
/**
 
/**
* Return a float parameter. <br>
+
* Return a float parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then converts it
 
* to a float.
 
* to a float.
 
*  
 
*  
Line 630: Line 499:
  
 
/**
 
/**
* Return a float parameter. <br>
+
* Returns a float parameter.
* This method uses <code>get()</code> to obtain the value, then convert it
+
* This method uses get() to obtain the value, then converts it
 
* to a float.
 
* to a float.
 
*  
 
*  
Line 649: Line 518:
 
/**
 
/**
 
* Returns a boolean parameter.
 
* Returns a boolean parameter.
* <p>
+
*  
 
* The value returned is true if and only if the parameter red is
 
* The value returned is true if and only if the parameter red is
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* <b>false</b>.
+
* false.
* <p>
 
 
*  
 
*  
 
* @param file
 
* @param file
Line 664: Line 532:
 
/**
 
/**
 
* Returns a boolean parameter.
 
* Returns a boolean parameter.
* <p>
+
*  
* The value returned is <b>true</b> if and only if the parameter red is
+
* The value returned is true if and only if the parameter red is
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* <b>false</b>.
+
* false.
* <p>
 
 
*  
 
*  
 
* @param node
 
* @param node
Line 683: Line 550:
 
/**
 
/**
 
* Returns a boolean parameter.
 
* Returns a boolean parameter.
* <p>
+
*  
* The value returned is <b>true</b> if and only if the parameter red is
+
* The value returned is true if and only if the parameter red is
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* <b>false</b>.
+
* false.
* <p>
 
 
*  
 
*  
 
* @param file
 
* @param file
Line 700: Line 566:
 
/**
 
/**
 
* Returns a boolean parameter.
 
* Returns a boolean parameter.
* <p>
+
*  
* The value returned is <b>true</b> if and only if the parameter red is
+
* The value returned is true if and only if the parameter red is
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
 
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* <b>false</b>.
+
* false.
* <p>
 
 
*  
 
*  
 
* @param node
 
* @param node
Line 720: Line 585:
 
/**
 
/**
 
* Checks if the given parameter exists. <br>
 
* Checks if the given parameter exists. <br>
* It checks that <code>get()</code> method does not return
+
* It checks that get() method does not return null.
* <code>null</code>.
 
 
*  
 
*  
 
* @param file
 
* @param file
Line 733: Line 597:
  
 
/**
 
/**
* Checks if the given parameter exists. <br>
+
* Checks if the given parameter exists.
* It checks that <code>get()</code> method does not return
+
* It checks that get() method does not return null.
* <code>null</code>.
 
 
*  
 
*  
 
* @param node
 
* @param node
Line 776: Line 639:
  
 
/**
 
/**
* Obtains a list of nodes that match the given XPath as a
+
* Obtains a list of nodes that match the given XPath as a Collection.
* <code>Collection</code>.
 
 
*  
 
*  
 
* @param file
 
* @param file
Line 785: Line 647:
 
*        file.
 
*        file.
 
* @return a list of nodes that match the given XPath as a
 
* @return a list of nodes that match the given XPath as a
*        <code>Collection</code>.
+
*        Collection.
 
*  
 
*  
 
* @throws XMLConfigException
 
* @throws XMLConfigException
Line 793: Line 655:
  
 
/**
 
/**
* Obtains a list of nodes that match the given XPath as a
+
* Obtains a list of nodes that match the given XPath as a Collection.
* <code>Collection</code>.
 
 
*  
 
*  
 
* @param node
 
* @param node
Line 801: Line 662:
 
*        parameter to read specified as relative path to the node
 
*        parameter to read specified as relative path to the node
 
* @return a list of nodes that match the given XPath as a
 
* @return a list of nodes that match the given XPath as a
*        <code>Collection</code>.
+
*        Collection.
 
*  
 
*  
 
* @throws XMLConfigException
 
* @throws XMLConfigException
Line 836: Line 697:
 
*/
 
*/
 
public static Node getNode(Node node, String xpath) throws XMLConfigException
 
public static Node getNode(Node node, String xpath) throws XMLConfigException
+
</syntaxhighlight>
 +
 
 +
 
 +
==XMLConfig configuration events management methods==
 +
<syntaxhighlight lang="java5">
 
/**
 
/**
 
* Add a ConfigurationListener.
 
* Add a ConfigurationListener.
Line 845: Line 710:
  
 
/**
 
/**
* Add a ConfigurationListener listening for events related to a single
+
* Adds a ConfigurationListener listening for events related to a single
 
* particular file.
 
* particular file.
 
*  
 
*  
 
* @param listener
 
* @param listener
*        a <tt>ConfigurationListener</tt> object
+
*        a ConfigurationListener object
 
* @param filename
 
* @param filename
*        a <tt>String</tt> containing the name of a file whose changes must
+
*        a String containing the name of a file whose changes must
 
*        be notified to the given listener
 
*        be notified to the given listener
 
*/
 
*/
Line 861: Line 726:
 
*  
 
*  
 
* @param listener
 
* @param listener
*        a <tt>ConfigurationListener</tt> object
+
*        a ConfigurationListener object
 
* @param fileList
 
* @param fileList
*        a <tt>List</tt> of <tt>String</tt> s containing the name of files
+
*        a List of String s containing the name of files
 
*        whose changes must be notified to the given listener
 
*        whose changes must be notified to the given listener
 
*/
 
*/
Line 869: Line 734:
 
      
 
      
 
/**
 
/**
* Remove a ConfigurationListener
+
* Removes a ConfigurationListener
 
*  
 
*  
 
* @param listener
 
* @param listener
Line 876: Line 741:
  
 
/**
 
/**
* Remove a ConfigurationListener listening for changes on a single file
+
* Removes a ConfigurationListener listening for changes on a single file
 
*  
 
*  
 
* @param listener
 
* @param listener
*        a <tt>ConfigurationListener</tt> object
+
*        a ConfigurationListener object
 
* @param filename
 
* @param filename
*        a <tt>String</tt> containing the name of a file whose changes must
+
*        a String containing the name of a file whose changes must
 
*        be notified to the given listener
 
*        be notified to the given listener
 
*/
 
*/
Line 890: Line 755:
 
*  
 
*  
 
* @param listener
 
* @param listener
*        a <tt>ConfigurationListener</tt> object
+
*        a ConfigurationListener object
 
* @param fileList
 
* @param fileList
*        a <tt>List</tt> of <tt>String</tt> s containing the name of files
+
*        a List of String s containing the name of files
 
*        whose changes must be notified to the given listener
 
*        whose changes must be notified to the given listener
 
*/
 
*/
 
public static void removeConfigurationListener(ConfigurationListener listener, List<String> fileList)
 
public static void removeConfigurationListener(ConfigurationListener listener, List<String> fileList)
 +
</syntaxhighlight>
  
/**
 
* Fires a ConfigurationEvent to all registered ConfigurationListener.
 
*
 
* @param event
 
*        event to fire
 
* @param immediate
 
*        if true the event is fired immediately
 
*/
 
protected static synchronized void prepareConfigurationEvent(ConfigurationEvent event, boolean immediate)
 
 
/**
 
* Fires the ConfigurationEvents to all registered ConfigurationListener.
 
*
 
*/
 
protected static synchronized void fireConfigurationEvents()
 
  
 +
==XMLConfig file management methods==
 +
<syntaxhighlight lang="java5">
 
/**
 
/**
* Return the URL to be used in order to load the given file.
+
* Loads a configuration file and, if necessary, notifies registered
 +
* listeners. This method can be used in order to preload the configuration
 +
* file.
 
*  
 
*  
 
* @param file
 
* @param file
 
*        the file to read
 
*        the file to read
* @return the URL to be used in order to load the given file.
+
* @return the complete URL used to load the file.
 
* @exception XMLConfigException
 
* @exception XMLConfigException
*            if the file could not be found.
+
*            if error occurs
 
*/
 
*/
public static synchronized URL getURL(String file) throws XMLConfigException
+
public static synchronized URL load(String file) throws XMLConfigException
  
 
/**
 
/**
* Return the URL to be used in order to load the given file.
+
* Loads a configuration file and, if necessary, notifies registered
 +
* listeners. This method can be used in order to preload the configuration
 +
* file.
 
*  
 
*  
 
* @param file
 
* @param file
Line 936: Line 793:
 
*        flag that indicates if this file can be changed and can be
 
*        flag that indicates if this file can be changed and can be
 
*        reloaded
 
*        reloaded
* @return the URL to be used in order to load the given file.
+
* @return the complete URL used to load the file.
 
* @exception XMLConfigException
 
* @exception XMLConfigException
*            if the file could not be found.
+
*            if error occurs
 
*/
 
*/
public static synchronized URL getURL(String file, ClassLoader classLoader, boolean force, boolean canBeReloaded)
+
public static synchronized URL load(String file, ClassLoader classLoader, boolean force, boolean canBeReloaded)
        throws XMLConfigException
+
        throws XMLConfigException
 +
/**
 +
* Discards all cached configuration files, notifies all registered
 +
* listeners, reload discarded files and notifies all registered listeners.
 +
*
 +
* @exception XMLConfigException
 +
*            if error occurs
 +
*/
 +
public static synchronized void reloadAll() throws XMLConfigException
  
 
/**
 
/**
* Reads a configuration file and caches it.
+
* If loaded discards the given file and notifies all registered listeners,
* <p>
+
* then reloads the given file (only if it was previously loaded) and
* The file is searched into the Java class path as another Java resource.
+
* notifies all registered listeners.
* See Java class loader documentation to understand this mechanism.
 
 
*  
 
*  
 
* @param file
 
* @param file
*        the file to read
+
*        the file to reload
* @return the read configuration as {@link org.w3c.dom.Document Document}.
+
* @exception XMLConfigException
*  
+
*           if error occurs
* @throws XMLConfigException
+
*/
*         if some error occurs.
+
public static synchronized void reload(String file) throws XMLConfigException
 +
 
 +
/**
 +
* Discards all cached files and notifies all listeners.
 
*/
 
*/
public static synchronized Document getDocument(String file) throws XMLConfigException
+
public static synchronized void discardAll()
   
+
 
 
/**
 
/**
* Reads a configuration file and caches it.
+
* Discards the given file. If the file was previously loaded then the
* <p>
+
* listeners will be notified, otherwise no action will be taken.
* The file is searched into the Java class path as another Java resource.
 
* See Java class loader documentation to understand this mechanism.
 
 
*  
 
*  
 
* @param file
 
* @param file
*        the file to read
+
*        the file to discard
* @param classLoader
 
*        the class loader to use to retrieve the file to read
 
* @param force
 
*        force the reload of file if already present in cache
 
* @param canBeReloaded
 
*        flag that indicates if this file can be changed and can be
 
*        reloaded
 
* @return the read configuration as {@link org.w3c.dom.Document Document}.
 
*
 
* @throws XMLConfigException
 
*        if some error occurs.
 
 
*/
 
*/
public static synchronized Document getDocument(String file, ClassLoader classLoader, boolean force,
+
public static synchronized void discard(String file)
        boolean canBeReloaded) throws XMLConfigException
 
  
 
/**
 
/**
* Checks if configuration is composed by multiple files.
+
* Returns an array of String s containing the names of the files
 +
* currently loaded into XMLConfig private cache.
 
*  
 
*  
* @param document
+
* @return an array of String s containing the names of the files
* @return if configuration is composed by multiple files.
+
*         currently loaded into XMLConfig private cache.
 
*/
 
*/
public static boolean isCompositeXMLConfig(Document document)
+
public static synchronized String[] getLoadedFiles()
 +
</syntaxhighlight>
  
/**
 
* @param baseUrl
 
* @param document
 
* @return the read configuration as {@link org.w3c.dom.Document Document}
 
* @throws XMLConfigException
 
*/
 
public static synchronized Document readCompositeXMLConfig(URL baseUrl, Document document)
 
            throws XMLConfigException
 
  
 +
==XMLConfig utility methods==
 +
<syntaxhighlight lang="java5">
 
/**
 
/**
* @param masterURL
+
* Sets the entity resolver used to resolve entities into the configuration
* @param xml
+
* files.
* @return the input with replaced properties
+
*
 +
* @param entityResolver
 +
*       EntityResolver to use in order to resolve entity. If
 +
*       null is specified then the default XML mechanism is
 +
*        used.
 
*/
 
*/
public static synchronized byte[] replaceXMLProperties(URL masterURL, byte[] xml)
+
public static synchronized void setEntityResolver(EntityResolver entityResolver)
  
 
/**
 
/**
* @param baseConfigPath
+
* Uses the default entity resolver to resolve entities into the
 +
* configuration files. The default entity resolver does not resolve
 +
* anything.
 +
*
 +
* @see #setEntityResolver(org.xml.sax.EntityResolver)
 
*/
 
*/
public static void setBaseConfigPath(String baseConfigPath)
+
public static synchronized void setDefaultEntityResolver()
  
 
/**
 
/**
* @return the base configuration path
+
* Returns the entity resolver for the configuration.
 +
*
 +
* @return the entity resolver for the configuration
 
*/
 
*/
public static String getBaseConfigPath()
+
public static synchronized EntityResolver getEntityResolver()
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 17:35, 21 December 2012

Class FQN: it.greenvulcano.configuration.XMLConfig

XMLConfig public static methods

/**
* Reads a value. If the XPath selects many nodes the values are appended
* together.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* 
* @return the searched value or null if the XPath select no
*         node.
* 
* @throws XMLConfigException
*         if some error occurs.
* 
*/
public static String get(String file, String xpath) throws XMLConfigException

/**
* Reads a value. If the XPath selects many nodes the values are appended
* together.
* 
* @param node
*        base for XPath
* @param xpath
*        parameter to read specified as relative path to the node.
* 
* @return the searched value or null if the XPath selects no node.
* 
* @throws XMLConfigException
*         if some error occurs.
* 
*/
public static String get(Node node, String xpath) throws XMLConfigException

/**
* Reads a value. If the XPath selects many nodes the values are appended
* together.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         selects no node or an error occurs.
* 
*/
public static String get(String file, String xpath, String defaultValue)

/**
* Reads a value. If the XPath selects many nodes the values are appended
* together.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static String get(Node node, String xpath, String defaultValue)

/**
* Reads a single encrypted value.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* @param keyId
*        the key id to be used for decryption, if null or empty is used
*        DEFAULT_KEY_ID
* @param canBeClear
*        if true the data can be unencrypted
* 
* @return the searched value or null if the XPath select no node.
* @throws XMLConfigException
*         if some error occurs.
* 
*/
public static String getDecrypted(String file, String xpath, String keyId, boolean canBeClear)
         throws XMLConfigException

/**
* Reads a single encrypted value.
* 
* @param node
*        base for XPath
* @param xpath
*        parameter to read specified as relative path to the node.
* @param keyId
*        the key id to be used for decryption, if null or empty is used
*        DEFAULT_KEY_ID
* @param canBeClear
*        if true the data can be unencrypted
* 
* @return the searched value or null if the XPath selects no node.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static String getDecrypted(Node node, String xpath, String keyId, boolean canBeClear)
        throws XMLConfigException
    
/**
* Reads a single encrypted value.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* @param keyId
*        the key id to be used for decryption, if null or empty is used
*        DEFAULT_KEY_ID
* @param canBeClear
*        if true the data can be unencrypted
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static String getDecrypted(String file, String xpath, String keyId, boolean canBeClear, String defaultValue)

/**
* Reads a single encrypted value.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param keyId
*        the key id to be used for decryption, if null or empty is used
*        DEFAULT_KEY_ID
* @param canBeClear
*        if true the data can be unencrypted
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static String getDecrypted(Node node, String xpath, String keyId, boolean canBeClear, String defaultValue)

/**
* Reads a single encrypted value.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
* 
* @return the searched value or null if the XPath select no node.
* @throws XMLConfigException
*         if some error occurs.
* 
*/
public static String getDecrypted(String file, String xpath) throws XMLConfigException

/**
* Reads a single encrypted value.
* 
* @param node
*        base for XPath
* @param xpath
*        parameter to read specified as relative path to the node.
* 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
* 
* @return the searched value or null if the XPath select no node.
* 
* @throws XMLConfigException
*         if some error occurs.
* 
*/
public static String getDecrypted(Node node, String xpath) throws XMLConfigException

/**
* Reads a single encrypted value.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* @param defaultValue
*        default value
* 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static String getDecrypted(String file, String xpath, String defaultValue)

/**
* Reads a single encrypted value.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param defaultValue
*        default value
* 
*        Sets the key id as DEFAULT_KEY_ID and canBeClear at true
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static String getDecrypted(Node node, String xpath, String defaultValue)

/**
* Decrypt a string encrypted by default XMLConfig key.
* 
* @param value
*        the value to decrypt
* 
* @return the decrypted value or value if not encrypted
* @throws XMLConfigException
*         if some error occurs.
* 
*/
 public static String getDecrypted(String value) throws XMLConfigException

/**
* Encrypt a string using default XMLConfig key.
* 
* @param value
*        the value to encrypt
* 
* @return the encrypted value
* @throws XMLConfigException
*         if some error occurs.
* 
*/
public static String getEncrypted(String value) throws XMLConfigException

/**
* Return an integer parameter. 
* This method uses get() to obtain the value, then convert it
* to an integer.
* 
* @param file
* @param xpath
* @return the searched integer value from the configuration.
* 
* @throws XMLConfigException
*         if any error occurs
*/
public static int getInteger(String file, String xpath) throws XMLConfigException

/**
* Return an integer parameter.
* This method uses get() to obtain the value, then convert it
* to an integer.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* 
* @return the searched integer value from the configuration.
* 
* @throws XMLConfigException
*         if an error occurs
*/
public static int getInteger(Node node, String xpath) throws XMLConfigException

/**
* Return an integer parameter.
* This method uses get() to obtain the value, then convert it
* to an integer.
* 
* @param file
*        the configuration file
* @param xpath
*        the XPath to search
* @param defaultValue
*        value to return if XPath not match
* @return the parameter value. If the parameter does not exists or an error
*         occurs then the specified default value will be returned.
* 
*/
public static int getInteger(final String file, final String xpath, final int defaultValue)

/**
* Return an integer parameter. 
* This method uses get() to obtain the value, then convert it
* to an integer.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static int getInteger(Node node, String xpath, int defaultValue)

/**
* Returns a long parameter.
* This method uses get() to obtain the value, then converts it
* to a long.
* 
* @param file
* @param xpath
* @return the searched long value from the configuration.
* 
* @throws XMLConfigException
*         if an error occurs
*/
public static long getLong(String file, String xpath) throws XMLConfigException

/**
* Returns a long parameter.
* This method uses get() to obtain the value, then convert it
* to a long.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* 
* @return the searched long value from the configuration.
* 
* @throws XMLConfigException
*         if an error occurs
*/
public static long getLong(Node node, String xpath) throws XMLConfigException

/**
* Returns a long parameter.
* This method uses get() to obtain the value, then convert it
* to a long.
* 
* @param file
* @param xpath
* @param defaultValue
* 
* @return the parameter value. If the parameter does not exists or an error
*         occurs then the specified default value will be returned.
* 
*/
public static long getLong(String file, String xpath, long defaultValue)

/**
* Returns a long parameter.
* This method uses get() to obtain the value, then convert it
* to a long.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param defaultValue
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static long getLong(Node node, String xpath, long defaultValue)

/**
* Returns a double parameter.
* This method uses get() to obtain the value, then convert it
* to a double.
* 
* @param file
* @param xpath
* @return the searched double value from the configuration.
* 
* @throws XMLConfigException
*         if an error occurs
*/
public static double getDouble(String file, String xpath) throws XMLConfigException

/**
* Returns a double parameter. 
* This method uses get() to obtain the value, then convert it
* to a double.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* 
* @return the searched double value from the configuration.
* 
* @throws XMLConfigException
*         if an error occurs
*/
public static double getDouble(Node node, String xpath) throws XMLConfigException

/**
* Return a double parameter.
* This method uses get() to obtain the value, then convert it
* to a double.
* 
* @param file
* @param xpath
* @param defaultValue
* 
* @return the parameter value. If the parameter does not exists or an error
*         occurs then the specified default value will be returned.
* 
*/
public static double getDouble(String file, String xpath, double defaultValue)

/**
* Returns a double parameter.
* This method uses get() to obtain the value, then convert it
* to a double.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static double getDouble(Node node, String xpath, double defaultValue)

/**
* Returns a float parameter.
* This method uses get() to obtain the value, then convert it
* to a float.
* 
* @param file
* @param xpath
* @return the searched float value from the configuration.
* 
* @throws XMLConfigException
*         if an error occurs
*/
public static float getFloat(String file, String xpath) throws XMLConfigException

/**
* Return a float parameter.
* This method uses get() to obtain the value, then converts it
* to a float.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* 
* @return the searched float value from the configuration.
* 
* @throws XMLConfigException
*         if an error occurs
*/
public static float getFloat(Node node, String xpath) throws XMLConfigException

/**
* Return a float parameter.
* This method uses get() to obtain the value, then converts it
* to a float.
* 
* @param file
* @param xpath
* @param defaultValue
* 
* @return the parameter value. If the parameter does not exists or an error
*         occurs then the specified default value will be returned.
* 
*/
public static float getFloat(String file, String xpath, float defaultValue)

/**
* Returns a float parameter.
* This method uses get() to obtain the value, then converts it
* to a float.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
* 
*/
public static float getFloat(Node node, String xpath, float defaultValue)

/**
* Returns a boolean parameter.
* 
* The value returned is true if and only if the parameter red is
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* false.
* 
* @param file
* @param xpath
* @return the boolean value of the parameter.
* @throws XMLConfigException
*/
public static boolean getBoolean(String file, String xpath) throws XMLConfigException

/**
* Returns a boolean parameter.
* 
* The value returned is true if and only if the parameter red is
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* false.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* 
* @return the searched boolean value from the configuration.
* 
* @throws XMLConfigException
*/
public static boolean getBoolean(Node node, String xpath) throws XMLConfigException

/**
* Returns a boolean parameter.
* 
* The value returned is true if and only if the parameter red is
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* false.
* 
* @param file
* @param xpath
* @param defaultValue
* @return the boolean value of the parameter. If the parameter does not
*         exists or an error occurs then the specified default value will
*         be returned.
*/
public static boolean getBoolean(String file, String xpath, boolean defaultValue)

/**
* Returns a boolean parameter.
* 
* The value returned is true if and only if the parameter red is
* equal, ignoring case, to "true" or "yes" or "on". Otherwise, it returns
* false.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to node.
* @param defaultValue
*        default value
* 
* @return the searched value or the specified default value if the XPath
*         select no node or an error occurs.
*/
public static boolean getBoolean(Node node, String xpath, boolean defaultValue)

/**
* Checks if the given parameter exists. <br>
* It checks that get() method does not return null.
* 
* @param file
* @param xpath
* @return if the given parameter exists.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static boolean exists(String file, String xpath) throws XMLConfigException

/**
* Checks if the given parameter exists.
* It checks that get() method does not return null.
* 
* @param node
* @param xpath
* @return if the given parameter exists
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static boolean exists(Node node, String xpath) throws XMLConfigException

/**
* Obtains a list of nodes that match the given XPath.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* @return a list of nodes that match the given XPath.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static NodeList getNodeList(String file, String xpath) throws XMLConfigException

/**
* Obtains a list of nodes that match the given XPath.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to the node
* @return a list of nodes that match the given XPath.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static NodeList getNodeList(Node node, String xpath) throws XMLConfigException

/**
* Obtains a list of nodes that match the given XPath as a Collection.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* @return a list of nodes that match the given XPath as a
*         Collection.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static Collection<Node> getNodeListCollection(String file, String xpath) throws XMLConfigException

/**
* Obtains a list of nodes that match the given XPath as a Collection.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to the node
* @return a list of nodes that match the given XPath as a
*         Collection.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static Collection<Node> getNodeListCollection(Node node, String xpath) throws XMLConfigException

/**
* Obtains a single node that matches the given XPath.
* 
* @param file
*        file to read
* @param xpath
*        parameter to read specified as absolute path to the root of the
*        file.
* @return a single node that matches the given XPath.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static Node getNode(String file, String xpath) throws XMLConfigException

/**
* Obtains a single node that matches the given XPath.
* 
* @param node
*        base node for XPath
* @param xpath
*        parameter to read specified as relative path to the node
* @return a single node that matches the given XPath.
* 
* @throws XMLConfigException
*         if some error occurs.
*/
public static Node getNode(Node node, String xpath) throws XMLConfigException


XMLConfig configuration events management methods

/**
* Add a ConfigurationListener.
* 
* @param listener
*/
public static void addConfigurationListener(ConfigurationListener listener)

/**
* Adds a ConfigurationListener listening for events related to a single
* particular file.
* 
* @param listener
*        a ConfigurationListener object
* @param filename
*        a String containing the name of a file whose changes must
*        be notified to the given listener
*/
public static void addConfigurationListener(ConfigurationListener listener, String filename)

/**
* Add a ConfigurationListener listening for events related to a particular
* set of files.
* 
* @param listener
*        a ConfigurationListener object
* @param fileList
*        a List of String s containing the name of files
*        whose changes must be notified to the given listener
*/
public static void addConfigurationListener(ConfigurationListener listener, List<String> fileList)
    
/**
* Removes a ConfigurationListener
* 
* @param listener
*/
public static void removeConfigurationListener(ConfigurationListener listener)

/**
* Removes a ConfigurationListener listening for changes on a single file
* 
* @param listener
*        a ConfigurationListener object
* @param filename
*        a String containing the name of a file whose changes must
*        be notified to the given listener
*/
public static void removeConfigurationListener(ConfigurationListener listener, String filename)

/**
* Remove a ConfigurationListener listening for changes on a subset of files
* 
* @param listener
*        a ConfigurationListener object
* @param fileList
*        a List of String s containing the name of files
*        whose changes must be notified to the given listener
*/
public static void removeConfigurationListener(ConfigurationListener listener, List<String> fileList)


XMLConfig file management methods

/**
* Loads a configuration file and, if necessary, notifies registered
* listeners. This method can be used in order to preload the configuration
* file.
* 
* @param file
*        the file to read
* @return the complete URL used to load the file.
* @exception XMLConfigException
*            if error occurs
*/
public static synchronized URL load(String file) throws XMLConfigException

/**
* Loads a configuration file and, if necessary, notifies registered
* listeners. This method can be used in order to preload the configuration
* file.
* 
* @param file
*        the file to read
* @param classLoader
*        the class loader to use to retrieve the file to read
* @param force
*        force the reload of file if already present in cache
* @param canBeReloaded
*        flag that indicates if this file can be changed and can be
*        reloaded
* @return the complete URL used to load the file.
* @exception XMLConfigException
*            if error occurs
*/
public static synchronized URL load(String file, ClassLoader classLoader, boolean force, boolean canBeReloaded)
         throws XMLConfigException
/**
* Discards all cached configuration files, notifies all registered
* listeners, reload discarded files and notifies all registered listeners.
* 
* @exception XMLConfigException
*            if error occurs
*/
public static synchronized void reloadAll() throws XMLConfigException

/**
* If loaded discards the given file and notifies all registered listeners,
* then reloads the given file (only if it was previously loaded) and
* notifies all registered listeners.
* 
* @param file
*        the file to reload
* @exception XMLConfigException
*            if error occurs
*/
public static synchronized void reload(String file) throws XMLConfigException

/**
* Discards all cached files and notifies all listeners.
*/
public static synchronized void discardAll()

/**
* Discards the given file. If the file was previously loaded then the
* listeners will be notified, otherwise no action will be taken.
* 
* @param file
*        the file to discard
*/
public static synchronized void discard(String file)

/**
* Returns an array of String s containing the names of the files
* currently loaded into XMLConfig private cache.
* 
* @return an array of String s containing the names of the files
*         currently loaded into XMLConfig private cache.
*/
public static synchronized String[] getLoadedFiles()


XMLConfig utility methods

/**
* Sets the entity resolver used to resolve entities into the configuration
* files.
* 
* @param entityResolver
*        EntityResolver to use in order to resolve entity. If
*        null is specified then the default XML mechanism is
*        used.
*/
public static synchronized void setEntityResolver(EntityResolver entityResolver)

/**
* Uses the default entity resolver to resolve entities into the
* configuration files. The default entity resolver does not resolve
* anything.
* 
* @see #setEntityResolver(org.xml.sax.EntityResolver)
*/
public static synchronized void setDefaultEntityResolver()

/**
* Returns the entity resolver for the configuration.
* 
* @return the entity resolver for the configuration
*/
public static synchronized EntityResolver getEntityResolver()