public class SurfConfiguration
extends org.apache.commons.configuration2.BaseHierarchicalConfiguration
implements org.apache.commons.configuration2.FileBasedConfiguration
FileBasedConfiguration that uses a SURF file to store information.
If a SURF configuration file is created by an instance of this class, it will be composed by a root SurfObject with the type name defined as
, and every property added to this SurfConfiguration instance will be a child of this SurfObject. i.e.:
*Configuration: property1 = value1 property2 = value2 property3 = value3 ;
In order to provide some backward compatibility, a Map may be used as the root object of the SURF configuration file. i.e.:
{
"property1" : value1
"property2" : value2
"property3" : value3
}
This Map version of SurfConfiguration is available to use only if the file has been already created. An instance of SurfConfiguration
will never use this approach by default.
An instance of SurfConfiguration may be gotten by using the following statement:
final Configuration config = new FileBasedConfigurationBuilder<SurfConfiguration>(SurfConfiguration.class)
.configure(new Parameters().fileBased().setFile(configurationFile)).getConfiguration();
To add properties there is the following statement:
config.addProperty(propertyName, propertyValue);
To get properties there is the following statement:
config.getProperty(propertyName);
The hierarchy model provided by Apache is also supported for SurfObjects and Maps:
config.getProperty("surfObjectName.propertyName");
or
config.getProperty("mapName.propertyName");
The current implementation lookup has a behave similar to the one of XMLConfiguration, what makes it possible to query the items of a List
using SurfObject's type name. This lookup is only supported by SurfObjects that have a type name:
config.getProperty("listName.SurfObjectTypeName(0)");
Here is an example of SURF file and how we would use the methods above:
*Configuration:
authenticated = true
sort = 'd'
name = "Jane Doe"
id = &bb8e7dbe-f0b4-4d94-a1cf-46ed0e920832
email = ^jane_doe@example.com
phone = +12015550123
aliases = [
"jdoe"
"janed"
]
homePage = <http://www.example.com/jdoe/>
salt = %Zm9vYmFy
joined = @2016-01-23,
credits = 123
favoriteThings = {
"aliquot" : "User's favorite word."
"amethyst" : "User's favorite stone."
}
!the list of colors said to make up the spectrum of a rainbow, in order
rainbow = [
*Color:
name = "red"
;
*Color:
name = "orange"
;
*Color:
name = "yellow"
;
*Color:
name = "green"
;
*Color:
name = "blue"
;
*Color:
name = "indigo"
;
*Color:
name = "violet"
;
]
;
{
authenticated : true
sort : 'd'
name : "Jane Doe"
id : &bb8e7dbe-f0b4-4d94-a1cf-46ed0e920832
email : ^jane_doe@example.com
phone : +12015550123
aliases : [
"jdoe"
"janed"
]
homePage : <http://www.example.com/jdoe/>
salt : %Zm9vYmFy
joined : @2016-01-23,
credits : 123
favoriteThings : {
"aliquot" : "User's favorite word."
"amethyst" : "User's favorite stone."
}
!the list of colors said to make up the spectrum of a rainbow, in order
rainbow : [
*Color:
name = "red"
;
*Color:
name = "orange"
;
*Color:
name = "yellow"
;
*Color:
name = "green"
;
*Color:
name = "blue"
;
*Color:
name = "indigo"
;
*Color:
name = "violet"
;
]
}
The following examples should work for both types of SurfConfiguration, the one with a SurfObject, and the one with a Map as
root object.
Here is an example of how to get a simple string property:
config.getProperty("name"); //returns "Jane Doe"
To get a property in its specific class, the class must be provided to the following method:
config.getProperty("favoriteThings", Boolean.class, "authenticated"); //returns true. If the class would not be provided, a string representation of the value would be returned.
Here is an example of how to get a property in a lower level in the hierarchy:
config.getProperty("favoriteThings.aliquot"); //returns "User's favorite word.".
Here is an example of how to make a lookup in a List:
config.getProperty("rainbow.Color(5)"); //returns "indigo". The lookup is zero-based, and it only works with SurfObjects with their type names properly set up.
Following Apache Configuration's documentation for XML, the index -1 can be used to create a new SurfObject in a List.
For example, if you have the following List:
rainbow : [
*Color:
name = "red"
;
*Color:
name = "orange"
;
*Color:
name = "yellow"
;
*Color:
name = "green"
;
*Color:
name = "blue"
;
*Color:
name = "indigo"
;
]
You can use the following statement for creating a new item:
config.addProperty("rainbow.Color(-1)"); //creates a new empty SurfObject.
This is how the List will look like:
rainbow : [
*Color:
name = "red"
;
*Color:
name = "orange"
;
*Color:
name = "yellow"
;
*Color:
name = "green"
;
*Color:
name = "blue"
;
*Color:
name = "indigo"
;
*Color:
;
]
Adding elements at the same time that a SurfObject is created is also allowed.
For example:
config.addProperty("rainbow.Color(-1).name", "violet"); //creates a new empty SurfObject and adds a property named "name" and with the value "violet" in it.
This is how the List created above would look like if we had used this statement:
rainbow : [
*Color:
name = "red"
;
*Color:
name = "orange"
;
*Color:
name = "yellow"
;
*Color:
name = "green"
;
*Color:
name = "blue"
;
*Color:
name = "indigo"
;
*Color:
name = "violet"
;
]
The SURF document serialized will always be formatted. See SurfSerializer.setFormatted(boolean) for more information.
| Constructor and Description |
|---|
SurfConfiguration() |
| Modifier and Type | Method and Description |
|---|---|
protected void |
addPropertyInternal(String key,
Object obj) |
protected Object |
getPropertyInternal(String key) |
Object |
getSurfDocument()
Returns the SURF document of this configuration.
|
protected boolean |
isEmptyInternal() |
void |
read(Reader in) |
protected void |
setPropertyInternal(String key,
Object obj) |
protected int |
sizeInternal() |
void |
write(Writer out) |
childConfigurationsAt, childConfigurationsAt, cloneNodeModel, configurationAt, configurationAt, configurationsAt, configurationsAt, createSubConfigurationForTrackedNode, getNodeModel, getSubConfigurationNodeSelector, getSubConfigurationParentModel, immutableChildConfigurationsAt, immutableConfigurationAt, immutableConfigurationAt, immutableConfigurationsAt, initSubConfigurationForThisParent, interpolatedConfiguration, subnodeConfigurationChanged, subsetaddNodes, addNodesInternal, addPropertyDirect, clearInternal, clearPropertyDirect, clearTree, clearTreeInternal, clone, containsKeyInternal, fetchNodeList, getExpressionEngine, getKeysInternal, getKeysInternal, getMaxIndex, getMaxIndexInternal, getModel, getRootElementName, getRootElementNameInternal, nodeDefined, nodeKey, resolveAddKey, resolveKey, resolveNodeKey, resolveUpdateKey, setExpressionEngine, toStringaddErrorLogListener, addProperty, append, beginRead, beginWrite, clear, clearProperty, cloneInterpolator, containsKey, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getList, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setSynchronizer, setThrowExceptionOnMissing, size, unlockaddEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEventsequals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitaddProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setProperty, subsetcontainsKey, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, immutableSubset, isEmpty, sizepublic void read(@Nonnull Reader in) throws org.apache.commons.configuration2.ex.ConfigurationException, IOException
If an empty file is provided to the FileHandler, then we create the root object using as the type name.
read in interface org.apache.commons.configuration2.io.FileBasedorg.apache.commons.configuration2.ex.ConfigurationException - if the root element is not an instance of SurfObject or Map, or if the Reader provided refers to a
non-existing file.IOException - if an I/O error occurs.public void write(@Nonnull Writer out) throws org.apache.commons.configuration2.ex.ConfigurationException, IOException
The configuration hierarchy is written to the given Writer, with SurfSerializer's formatter set up.
write in interface org.apache.commons.configuration2.io.FileBasedorg.apache.commons.configuration2.ex.ConfigurationException - if the root element is not an instance of SurfObject or Map, or if the Reader provided refers to a
non-existing file.IOException - if an I/O error occurs.SurfSerializer.setFormatted(boolean)protected void addPropertyInternal(@Nonnull String key, @Nullable Object obj)
This implementation delegates to setPropertyInternal(String, Object) in order to not accept duplicated keys in the same level.
addPropertyInternal in class org.apache.commons.configuration2.AbstractHierarchicalConfiguration<org.apache.commons.configuration2.tree.ImmutableNode>protected void setPropertyInternal(@Nonnull String key, @Nullable Object obj)
If the object provided is one of the data structures supported by this implementation, it manually converts and adds it to the hierarchy, otherwise, this
method just delegates to AbstractHierarchicalConfiguration.setPropertyInternal(String, Object).
(-1) is supported only for creation of SurfObjects.setPropertyInternal in class org.apache.commons.configuration2.AbstractHierarchicalConfiguration<org.apache.commons.configuration2.tree.ImmutableNode>IllegalArgumentException - If a non existing key is given in one of the middle levels on the hierarchy.NoSuchElementException - If an indexed key is provided for an object that exists in the hierarchy, but does not have an entry for the given index.protected Object getPropertyInternal(@Nonnull String key)
getPropertyInternal in class org.apache.commons.configuration2.AbstractHierarchicalConfiguration<org.apache.commons.configuration2.tree.ImmutableNode>protected int sizeInternal()
sizeInternal in class org.apache.commons.configuration2.AbstractHierarchicalConfiguration<org.apache.commons.configuration2.tree.ImmutableNode>protected boolean isEmptyInternal()
isEmptyInternal in class org.apache.commons.configuration2.AbstractHierarchicalConfiguration<org.apache.commons.configuration2.tree.ImmutableNode>Copyright © 2017 GlobalMentor, Inc.. All rights reserved.