Package org.jivesoftware.util
Class XMLProperties
java.lang.Object
org.jivesoftware.util.XMLProperties
Provides the ability to use simple XML property files. Each property is
in the form X.Y.Z, which would map to an XML snippet of:
<X> <Y> <Z>someValue</Z> </Y> </X>The XML file is passed in to the constructor and must be readable and writable. Setting property values will automatically persist those value to disk. The file encoding used is UTF-8.
- Author:
- Derek DeMoro, Iain Shigeoka
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
Adds the given value to the list of values represented by the property name.void
deleteProperty
(String name) Deletes the specified property.Returns a list of names for all properties found in the XML file.getAttribute
(String name, String attribute) Returns the value of the attribute of the given property name ornull
if it doesn't exist.getChildProperties
(String name) Return all values who's path matches the given property name as a String array, or an empty array if the if there are no children.String[]
getChildrenProperties
(String parent) Return all children property names of a parent property as a String array, or an empty array if the if there are no children.static XMLProperties
Creates a new empty XMLProperties object.static XMLProperties
Creates a new XMLProperties object with content loaded from a stream.getProperties
(String name, boolean ignored) Return all values who's path matches the given property name as a String array, or an empty array if the if there are no children.getProperty
(String name) Returns the value of the specified property.getProperty
(String name, boolean ignoreEmpty) Returns the value of the specified property.void
migrateProperty
(String name) Convenience routine to migrate an XML property into the database storage method.removeAttribute
(String name, String attribute) Removes the given attribute from the XML document.boolean
removeFromList
(String propertyName, String value) Removes the given value from the list of values represented by the property name.void
setProperties
(String name, List<String> values) Sets a property to an array of values.void
setProperties
(Map<String, String> propertyMap) boolean
setProperty
(String name, String value) Sets the value of the specified property.
-
Constructor Details
-
XMLProperties
Creates a new XMLProperties object.- Parameters:
file
- the file that properties should be read from and written to.- Throws:
IOException
- if an error occurs loading the properties.
-
-
Method Details
-
getNonPersistedInstance
Creates a new empty XMLProperties object. The object will only have an empty root element. Note that an instance created by this constructor cannot be used to persist changes (as it is not backed by a file).- Returns:
- an XMLProperties instance that is empty
- Throws:
IOException
- if an exception occurs initializing the properties
-
getNonPersistedInstance
Creates a new XMLProperties object with content loaded from a stream. Note that an instance created by this constructor cannot be used to persist changes (as it is not backed by a file).- Parameters:
in
- the input stream of XML.- Returns:
- an XMLProperties instance populated with data from the stream.
- Throws:
IOException
- if an exception occurs when reading the stream.
-
getProperty
Returns the value of the specified property.- Parameters:
name
- the name of the property to get.- Returns:
- the value of the specified property.
-
getProperty
Returns the value of the specified property.- Parameters:
name
- the name of the property to get.ignoreEmpty
- Ignore empty property values (return null)- Returns:
- the value of the specified property.
-
getProperties
Return all values who's path matches the given property name as a String array, or an empty array if the if there are no children. This allows you to retrieve several values with the same property name. For example, consider the XML file entry:<foo> <bar> <prop>some value</prop> <prop>other value</prop> <prop>last value</prop> </bar> </foo>
If you call getProperties("foo.bar.prop") will return a string array containing {"some value", "other value", "last value"}.- Parameters:
name
- the name of the property to retrieveignored
- unused parameter- Returns:
- all child property values for the given node name.
-
getChildProperties
Return all values who's path matches the given property name as a String array, or an empty array if the if there are no children. This allows you to retrieve several values with the same property name. For example, consider the XML file entry:<foo> <bar> <prop>some value</prop> <prop>other value</prop> <prop>last value</prop> </bar> </foo>
If you call getProperties("foo.bar.prop") will return a string array containing {"some value", "other value", "last value"}.- Parameters:
name
- the name of the property to retrieve- Returns:
- all child property values for the given node name.
-
getAttribute
Returns the value of the attribute of the given property name ornull
if it doesn't exist.- Parameters:
name
- the property name to lookup - ie, "foo.bar"attribute
- the name of the attribute, ie "id"- Returns:
- the value of the attribute of the given property or
null
if it doesn't exist.
-
removeAttribute
Removes the given attribute from the XML document.- Parameters:
name
- the property name to lookup - ie, "foo.bar"attribute
- the name of the attribute, ie "id"- Returns:
- the value of the attribute of the given property or
null
if it did not exist.
-
setProperties
Sets a property to an array of values. Multiple values matching the same property is mapped to an XML file as multiple elements containing each value. For example, using the name "foo.bar.prop", and the value string array containing {"some value", "other value", "last value"} would produce the following XML:<foo> <bar> <prop>some value</prop> <prop>other value</prop> <prop>last value</prop> </bar> </foo>
- Parameters:
name
- the name of the property.values
- the values for the property (can be empty but not null).
-
addToList
Adds the given value to the list of values represented by the property name. The property is created if it did not already exist.- Parameters:
propertyName
- The name of the property list to changevalue
- The value to be added to the list- Returns:
- True if the value was added to the list; false if the value was already present
-
removeFromList
Removes the given value from the list of values represented by the property name. The property is deleted if it no longer contains any values.- Parameters:
propertyName
- The name of the property list to changevalue
- The value to be removed from the list- Returns:
- True if the value was removed from the list; false if the value was not found
-
getAllPropertyNames
Returns a list of names for all properties found in the XML file.- Returns:
- Names for all properties in the file
-
getChildrenProperties
Return all children property names of a parent property as a String array, or an empty array if the if there are no children. For example, given the propertiesX.Y.A
,X.Y.B
, andX.Y.C
, then the child properties ofX.Y
areA
,B
, andC
.- Parameters:
parent
- the name of the parent property.- Returns:
- all child property values for the given parent.
-
setProperty
Sets the value of the specified property. If the property doesn't currently exist, it will be automatically created.- Parameters:
name
- the name of the property to set.value
- the new value for the property.- Returns:
true
if the property was correctly saved to file, otherwisefalse
-
deleteProperty
Deletes the specified property.- Parameters:
name
- the property to delete.
-
migrateProperty
Convenience routine to migrate an XML property into the database storage method. Will check for the XML property being null before migrating.- Parameters:
name
- the name of the property to migrate.
-
setProperties
-