edu.rice.cs.util
Class XMLConfig

java.lang.Object
  edu.rice.cs.util.XMLConfig

public class XMLConfig
extends Object

XML configuration management.

This class uses DOM paths of a specific form to refer to nodes in the XML document. Consider this XML structure: abc def The path "foo/bar" refers to the value "abc". The path "foo/fum" refers to the value "def". If this form is used, there may be only #text or #comment nodes in the node. All #text nodes will be concatenated and then stripped of whitespace at the beginning and the end. The path "foo/fum.fee" refers to the value "xyz". The path "foo.a" refers to the value "foo.a". When using getMultiple, any node or attribute name can be substituted with "*" to get all elements: The path "foo/*" returns both the value "abc" and "def".

Author:

Mathias Ricken

Nested Class Summary

static class

XMLConfig.XMLConfigException Exception in XMLConfig methods.

Field Summary

private Document	_document XML document.
private XMLConfig	_parent XMLConfig to delegate to, or null.
private Node	_startNode Node where this XMLConfig starts if delegation is used, or null.
static String	NL Newline string.

Constructor Summary

XMLConfig()
Creates an empty configuration.

XMLConfig(File f)
Creates a configuration from a file.

XMLConfig(InputStream is)
Creates a configuration from an input stream.

XMLConfig(Reader r)
Creates a configuration from a reader.

XMLConfig(String filename)
Creates a configuration from a file name.

XMLConfig(XMLConfig parent, Node node)
Creates a configuration that is a part of another configuration, starting at the specified node.

Method Summary

Node	createNode(String path) Create the node specified by the DOM path.
Node	createNode(String path, Node n) Create the node specified by the DOM path.
Node	createNode(String path, Node n, boolean overwrite) Create the node specified by the DOM path.
String	get(String path) Returns the value as specified by the DOM path.
String	get(String path, Node root) Returns the value as specified by the DOM path.
String	get(String path, Node root, String defaultVal) Returns the value as specified by the DOM path, or the default value if the value could not be found.
String	get(String path, String defaultVal) Returns the value as specified by the DOM path, or the default value if the value could not be found.
boolean	getBool(String path) Returns the value as specified by the DOM path.
boolean	getBool(String path, boolean defaultVal) Returns the value as specified by the DOM path, or the default value if the value could not be found.
boolean	getBool(String path, Node root) Returns the value as specified by the DOM path.
boolean	getBool(String path, Node root, boolean defaultVal) Returns the value as specified by the DOM path, or the default value if the value could not be found.
int	getInt(String path) Returns the value as specified by the DOM path.
int	getInt(String path, int defaultVal) Returns the value as specified by the DOM path, or the default value if the value could not be found.
int	getInt(String path, Node root) Returns the value as specified by the DOM path.
int	getInt(String path, Node root, int defaultVal) Returns the value as specified by the DOM path, or the default value if the value could not be found.
List<String>	getMultiple(String path) Returns the value as specified by the DOM path.
List<String>	getMultiple(String path, Node root) Returns the value as specified by the DOM path.
private void	getMultipleAddAttributesHelper(String path, Node n, List<Node> accum)
private void	getMultipleHelper(String path, Node n, List<Node> accum, boolean dotRead) Returns the value as specified by the DOM path.
static String	getNodePath(Node n) Return the path of a node as it is used in XMLConfig.
List<Node>	getNodes(String path) Returns the nodes as specified by the DOM path.
List<Node>	getNodes(String path, Node root) Returns the nodes as specified by the DOM path.
private void	init(InputSource is) Initialize this XML configuration.
boolean	isDelegated()
void	save(File f) Saves configuration to a file.
void	save(OutputStream os) Saves configuration to an output stream
void	save(String filename) Saves configuration to a file specified by a file name.
Node	set(String path, String value) Set the value of the node or attribute specified by the DOM path.
Node	set(String path, String value, boolean overwrite) Set the value of the node or attribute specified by the DOM path.
Node	set(String path, String value, Node n, boolean overwrite) Set the value of the node or attribute specified by the DOM path.
String	toString() Returns a string representation of the object.

Methods inherited from class java.lang.Object

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

Field Detail

NL

public static final String NL

Newline string.

_document

private Document _document

XML document.

_parent

private XMLConfig _parent

XMLConfig to delegate to, or null.

_startNode

private Node _startNode

Node where this XMLConfig starts if delegation is used, or null.

Constructor Detail

XMLConfig

public XMLConfig()

Creates an empty configuration.

XMLConfig

public XMLConfig(InputStream is)

Creates a configuration from an input stream.

Parameters:

is - input stream

XMLConfig

public XMLConfig(Reader r)

Creates a configuration from a reader.

Parameters:

r - reader

XMLConfig

public XMLConfig(XMLConfig parent,
                 Node node)

Creates a configuration that is a part of another configuration, starting at the specified node.

Parameters:

parent - the configuration that contains this part

node - the node in the parent configuration where this part starts

XMLConfig

public XMLConfig(File f)

Creates a configuration from a file.

Parameters:

f - file

XMLConfig

public XMLConfig(String filename)

Creates a configuration from a file name.

Parameters:

filename - file name

Method Detail

init

private void init(InputSource is)

Initialize this XML configuration.

Parameters:

is - the XML input source

isDelegated

public boolean isDelegated()

save

public void save(OutputStream os)

Saves configuration to an output stream

Parameters:

os - output stream

save

public void save(File f)

Saves configuration to a file.

Parameters:

f - file

save

public void save(String filename)

Saves configuration to a file specified by a file name.

Parameters:

filename - file name

get

public String get(String path)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

Returns:

value.

get

public String get(String path,
                  Node root)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

root - node where the search should start

Returns:

value.

get

public String get(String path,
                  String defaultVal)

Returns the value as specified by the DOM path, or the default value if the value could not be found.

Parameters:

path - DOM path

defaultVal - default value in case value is not in DOM

Returns:

value.

get

public String get(String path,
                  Node root,
                  String defaultVal)

Returns the value as specified by the DOM path, or the default value if the value could not be found.

Parameters:

path - DOM path

root - node where the search should start

defaultVal - default value in case value is not in DOM

Returns:

value.

getInt

public int getInt(String path)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

Returns:

value.

Throws:

IllegalArgumentException

getInt

public int getInt(String path,
                  Node root)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

root - node where the search should start

Returns:

value.

Throws:

IllegalArgumentException

getInt

public int getInt(String path,
                  int defaultVal)

Returns the value as specified by the DOM path, or the default value if the value could not be found.

Parameters:

path - DOM path

defaultVal - default value in case value is not in DOM

Returns:

value.

Throws:

IllegalArgumentException

getInt

public int getInt(String path,
                  Node root,
                  int defaultVal)

Returns the value as specified by the DOM path, or the default value if the value could not be found.

Parameters:

path - DOM path

root - node where the search should start

defaultVal - default value in case value is not in DOM

Returns:

value.

Throws:

IllegalArgumentException

getBool

public boolean getBool(String path)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

Returns:

value.

Throws:

IllegalArgumentException

getBool

public boolean getBool(String path,
                       Node root)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

root - node where the search should start

Returns:

value.

Throws:

IllegalArgumentException

getBool

public boolean getBool(String path,
                       boolean defaultVal)

Returns the value as specified by the DOM path, or the default value if the value could not be found.

Parameters:

path - DOM path

defaultVal - default value in case value is not in DOM

Returns:

value.

Throws:

IllegalArgumentException

getBool

public boolean getBool(String path,
                       Node root,
                       boolean defaultVal)

Returns the value as specified by the DOM path, or the default value if the value could not be found.

Parameters:

path - DOM path

root - node where the search should start

defaultVal - default value in case value is not in DOM

Returns:

value.

Throws:

IllegalArgumentException

getMultiple

public List<String> getMultiple(String path)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

Returns:

list of values.

getMultiple

public List<String> getMultiple(String path,
                                Node root)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

root - node where the search should start

Returns:

list of values.

getNodes

public List<Node> getNodes(String path)

Returns the nodes as specified by the DOM path.

Parameters:

path - DOM path

Returns:

list of nodes.

getNodes

public List<Node> getNodes(String path,
                           Node root)

Returns the nodes as specified by the DOM path.

Parameters:

path - DOM path

root - node where the search should start

Returns:

list of nodes.

getMultipleHelper

private void getMultipleHelper(String path,
                               Node n,
                               List<Node> accum,
                               boolean dotRead)

Returns the value as specified by the DOM path.

Parameters:

path - DOM path

n - node where the search begins

accum - accumulator

dotRead - whether a dot has been read

getMultipleAddAttributesHelper

private void getMultipleAddAttributesHelper(String path,
                                            Node n,
                                            List<Node> accum)

set

public Node set(String path,
                String value)

Set the value of the node or attribute specified by the DOM path.

Parameters:

path - DOM path

value - node or attribute value

Returns:

the node that was created, or the parent node of the attribute if it was an attribute

set

public Node set(String path,
                String value,
                boolean overwrite)

Set the value of the node or attribute specified by the DOM path.

Parameters:

path - DOM path

value - node or attribute value

overwrite - whether to overwrite (true) or add (false)

Returns:

the node that was created, or the parent node of the attribute if it was an attribute

set

public Node set(String path,
                String value,
                Node n,
                boolean overwrite)

Set the value of the node or attribute specified by the DOM path.

Parameters:

path - DOM path

value - node or attribute value

n - node where the search should start

overwrite - whether to overwrite (true) or add (false) -- only applies for last node!

Returns:

the node that was created, or the parent node of the attribute if it was an attribute

createNode

public Node createNode(String path)

Create the node specified by the DOM path.

Parameters:

path - DOM path

Returns:

the node that was created, or the parent node of the attribute if it was an attribute

createNode

public Node createNode(String path,
                       Node n)

Create the node specified by the DOM path.

Parameters:

path - DOM path

n - node where the search should start, or null for the root

Returns:

the node that was created, or the parent node of the attribute if it was an attribute

createNode

public Node createNode(String path,
                       Node n,
                       boolean overwrite)

Create the node specified by the DOM path.

Parameters:

path - DOM path

n - node where the search should start, or null for the root

overwrite - whether to overwrite (true) or add (false) -- only applies for last node!

Returns:

the node that was created, or the parent node of the attribute if it was an attribute

toString

public String toString()

Returns a string representation of the object.

Overrides:

toString in class Object

Returns:

a string representation of the object.

getNodePath

public static String getNodePath(Node n)

Return the path of a node as it is used in XMLConfig.

Parameters:

n - node

Returns:

path