org.krysalis.barcode4j.configuration.Configuration Maven / Gradle / Ivy
Show all versions of barcode4j Show documentation
package org.krysalis.barcode4j.configuration;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* This class is essentially a copy of org.apache.avalon.framework.configuration.Configuration
*
* Configuration is an interface encapsulating a configuration node
* used to retrieve configuration values.
*
*
* This is a "read only" interface preventing applications from modifying their
* own configurations. Once it is created, the information never changes.
*
* Data Model
*
* The data model is a subset of XML's; a single-rooted hierarchical tree where each
* node can contain multiple attributes, and leaf nodes can also
* contain a value. Reflecting this, Configurations are
* usually built from an XML file by the DefaultConfigurationBuilder
* class, or directly by a SAX parser using a SAXConfigurationHandler or
* NamespacedSAXConfigurationHandler event handler.
*
* Namespace support
*
* Since version 4.1, each Configuration node has a namespace
* associated with it, in the form of a string, accessible through {@link
* #getNamespace}. If no namespace is present, getNamespace will
* return blank (""). See DefaultConfigurationBuilder for details on how
* XML namespaces are mapped to Configuration namespaces.
*
* Example
*
* As an example, consider two Configurations (with and without
* namespaces) built from this XML:
*
*
* <my-system version="1.3" xmlns:doc="http://myco.com/documentation">
* <doc:desc>This is a highly fictitious config file</doc:desc>
* <widget name="fooWidget" initOrder="1" threadsafe="true"/>
* </my-system>
*
* If namespace support is enabled (eg through
* DefaultConfigurationBuilder#DefaultConfigurationBuilder(boolean) new
* DefaultConfigurationBuilder(true)), then the xmlns:doc element
* will not translate into a Configuration attribute, and the
* doc:desc element will become a Configuration node
* with name "desc" and namespace "http://myco.com/documentation". The
* widget element will have namespace "".
*
* If namespace support is disabled (the default for
* DefaultConfigurationBuilder), the above XML will translate directly to
* Configuration nodes. The my-system node will have
* an attribute named "xmlns:doc", and a child called "doc:desc".
*
*
* Assuming the Configuration object is named conf,
* here is how the data could be retrieved:
*
*
* Code No namespaces With namespaces
* conf.{@link #getName getName}() my-system
* conf.{@link #getAttributeNames getAttributeNames}().length
* 2 1
* conf.{@link #getChildren() getChildren}().length
* 2
* conf.{@link #getAttributeAsFloat(String) getAttributeAsFloat}("version")
* 1.3
* conf.{@link #getChild(String) getChild}("widget").{@link #getAttribute(String) getAttribute}("name")
* fooWidget
* conf.{@link #getChild(String) getChild}("widget")
* .{@link #getAttributeAsBoolean(String) getAttributeAsBoolean}("threadsafe")
* true
* conf.{@link #getChild(String) getChild}("widget").{@link #getLocation getLocation}()
* file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60
* conf.{@link #getChild(String) getChild}("desc").{@link #getName getName}()
* desc (see {@link #getChild(String)}) desc
* conf.{@link #getChild(String) getChild}("doc:desc").{@link #getName getName}()
* doc:desc doc:desc (see {@link #getChild(String)})
* conf.{@link #getChild(String) getChild}("desc").{@link #getValue() getValue}()
* {@link ConfigurationException} This is a highly fictitious config file
* conf.{@link #getChild(String) getChild}("doc:desc").{@link #getValue() getValue}()
* This is a highly fictitious config file {@link ConfigurationException}
* conf.{@link #getChild(String) getChild}("desc").{@link #getNamespace getNamespace}()
* http://myco.com/documentation"
*
*
* Type-safe utility methods are provided for retrieving attribute and element
* values as String, int, long,
* float and boolean.
*
* Miscellanea
*
* Currently, the configuration tree can only be traversed one node at a time,
* eg., through {@link #getChild(String) getChild("foo")} or {@link #getChildren()}. In
* a future release, it may be possible to access child nodes with an XPath-like
* syntax.
*
*
* Checking for the existence of an attribute can be done as follows:
*
*
* String value = conf.getAttribute( "myAttribute", null );
* if ( null == value )
* {
* // Do the processing applicable if the attribute isn't present.
* }
*
*
* @author Avalon Development Team
* @version $Id: Configuration.java 506231 2007-02-12 02:36:54Z crossley $
*/
public interface Configuration {
/**
* Return the name of the node.
*
* @return name of the Configuration node.
*/
@NotNull
String getName();
/**
* Return a string describing location of Configuration.
* Location can be different for different mediums (ie "file:line" for normal XML files or
* "table:primary-key" for DB based configurations);
*
* @return a string describing location of Configuration
*/
String getLocation();
/**
* Returns a string indicating which namespace this Configuration node
* belongs to.
*
*
* What this returns is dependent on the configuration file and the
* Configuration builder. If the Configuration builder does not support
* namespaces, this method will return a blank string.
*
* In the case of DefaultConfigurationBuilder, the namespace will
* be the URI associated with the XML element. Eg.,:
*
* <foo xmlns:x="http://blah.com">
* <x:bar/>
* </foo>
*
* The namespace of foo will be "", and the namespace of
* bar will be "http://blah.com".
*
* @return a String identifying the namespace of this Configuration.
* @throws ConfigurationException if an error occurs
* @since 4.1
*/
@NotNull // returns empty string if no namespace
String getNamespace() throws ConfigurationException;
/**
* Return a new Configuration instance encapsulating the
* specified child node.
*
* If no such child node exists, an empty Configuration will be
* returned, allowing constructs such as
* conf.getChild("foo").getChild("bar").getChild("baz").{@link
* #getValue(String) getValue}("default");
*
*
* If you wish to get a null return when no element is present,
* use {@link #getChild(String, boolean) getChild("foo", false)}.
*
*
* @param child The name of the child node.
* @return Configuration
*/
@NotNull
Configuration getChild(@NotNull String child);
/**
* Return a Configuration instance encapsulating the specified
* child node.
*
* @param child The name of the child node.
* @param createNew If true, a new Configuration
* will be created and returned if the specified child does not exist. If
* false, null will be returned when the specified
* child doesn't exist.
* @return Configuration
*/
@Nullable
Configuration getChild(@NotNull String child, boolean createNew);
/**
* Return an Array of Configuration
* elements containing all node children. The array order will reflect the
* order in the source config file.
*
* @return All child nodes
*/
Configuration[] getChildren();
/**
* Return an Array of Configuration
* elements containing all node children with the specified name. The array
* order will reflect the order in the source config file.
*
* @param name The name of the children to get.
* @return The child nodes with name name
*/
Configuration[] getChildren(@NotNull String name);
/**
* Return an array of all attribute names.
*
* The order of attributes in this array can not be relied on. As
* with XML, a Configuration's attributes are an
* unordered set. If your code relies on order, eg
* conf.getAttributeNames()[0], then it is liable to break if a
* different XML parser is used.
*
*
* @return a String[] value
*/
String[] getAttributeNames();
/**
* Return the value of specified attribute.
*
* @param paramName The name of the parameter you ask the value of.
* @return String value of attribute.
* @throws ConfigurationException If no attribute with that name exists.
*/
@NotNull
String getAttribute(@NotNull String paramName) throws ConfigurationException;
/**
* Return the int value of the specified attribute contained
* in this node.
*
* @param paramName The name of the parameter you ask the value of.
* @return int value of attribute
* @throws ConfigurationException If no parameter with that name exists.
* or if conversion to int fails.
*/
int getAttributeAsInteger(@NotNull String paramName) throws ConfigurationException;
/**
* Returns the value of the attribute specified by its name as a
* long.
*
* @param name The name of the parameter you ask the value of.
* @return long value of attribute
* @throws ConfigurationException If no parameter with that name exists.
* or if conversion to long fails.
*/
long getAttributeAsLong(@NotNull String name) throws ConfigurationException;
/**
* Return the float value of the specified parameter contained
* in this node.
*
* @param paramName The name of the parameter you ask the value of.
* @return float value of attribute
* @throws ConfigurationException If no parameter with that name exists.
* or if conversion to float fails.
*/
float getAttributeAsFloat(@NotNull String paramName) throws ConfigurationException;
/**
* Return the double value of the specified parameter contained
* in this node.
*
* @param paramName The name of the parameter you ask the value of.
* @return double value of attribute
* @throws ConfigurationException If no parameter with that name exists.
* or if conversion to double fails.
*/
double getAttributeAsDouble(@NotNull String paramName) throws ConfigurationException;
/**
* Return the boolean value of the specified parameter contained
* in this node.
*
* @param paramName The name of the parameter you ask the value of.
* @return boolean value of attribute
* @throws ConfigurationException If no parameter with that name exists.
* or if conversion to boolean fails.
*/
boolean getAttributeAsBoolean(@NotNull String paramName) throws ConfigurationException;
/**
* Return the String value of the node.
*
* @return the value of the node.
* @throws ConfigurationException if the value is null
*/
@NotNull
String getValue() throws ConfigurationException;
/**
* Return the int value of the node.
*
* @return the value of the node.
* @throws ConfigurationException If conversion to int fails.
*/
int getValueAsInteger() throws ConfigurationException;
/**
* Return the float value of the node.
*
* @return the value of the node.
* @throws ConfigurationException If conversion to float fails.
*/
float getValueAsFloat() throws ConfigurationException;
/**
* Return the double value of the node.
*
* @return the value of the node.
* @throws ConfigurationException If conversion to double fails.
*/
double getValueAsDouble() throws ConfigurationException;
/**
* Return the boolean value of the node.
*
* @return the value of the node.
* @throws ConfigurationException If conversion to boolean fails.
*/
boolean getValueAsBoolean() throws ConfigurationException;
/**
* Return the long value of the node.
*
* @return the value of the node.
* @throws ConfigurationException If conversion to long fails.
*/
long getValueAsLong() throws ConfigurationException;
/**
* Returns the value of the configuration element as a String.
* If the configuration value is not set, the default value will be used.
*
* @param defaultValue The default value desired.
* @return String value of the Configuration, or default if none specified.
*/
String getValue(@Nullable String defaultValue);
/**
* Returns the value of the configuration element as an int.
* If the configuration value is not set, the default value will be used.
*
* @param defaultValue The default value desired.
* @return int value of the Configuration, or default
* if none specified.
*/
int getValueAsInteger(int defaultValue);
/**
* Returns the value of the configuration element as a long.
* If the configuration value is not set, the default value will be used.
*
* @param defaultValue The default value desired.
* @return long value of the Configuration, or default
* if none specified.
*/
long getValueAsLong(long defaultValue);
/**
* Returns the value of the configuration element as a float.
* If the configuration value is not set, the default value will be used.
*
* @param defaultValue The default value desired.
* @return float value of the Configuration, or default
* if none specified.
*/
float getValueAsFloat(float defaultValue);
/**
* Returns the value of the configuration element as a double.
* If the configuration value is not set, the default value will be used.
*
* @param defaultValue The default value desired.
* @return float value of the Configuration, or default
* if none specified.
*/
double getValueAsDouble(double defaultValue);
/**
* Returns the value of the configuration element as a boolean.
* If the configuration value is not set, the default value will be used.
*
* @param defaultValue The default value desired.
* @return boolean value of the Configuration, or default
* if none specified.
*/
boolean getValueAsBoolean(boolean defaultValue);
/**
* Returns the value of the attribute specified by its name as a
* String, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return String value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
*/
String getAttribute(@NotNull String name, @Nullable String defaultValue);
/**
* Returns the value of the attribute specified by its name as a
* int, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return int value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
*/
int getAttributeAsInteger(@NotNull String name, int defaultValue);
/**
* Returns the value of the attribute specified by its name as a
* long, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return long value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
*/
long getAttributeAsLong(@NotNull String name, long defaultValue);
/**
* Returns the value of the attribute specified by its name as a
* float, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return float value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
*/
float getAttributeAsFloat(@NotNull String name, float defaultValue);
/**
* Returns the value of the attribute specified by its name as a
* double, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return float value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
*/
double getAttributeAsDouble(@NotNull String name, double defaultValue);
/**
* Returns the value of the attribute specified by its name as a
* boolean, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return boolean value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
*/
boolean getAttributeAsBoolean(@NotNull String name, boolean defaultValue);
}