de.bb.util
Class XmlFile

java.lang.Object
  de.bb.util.XmlFile

public class XmlFile
extends java.lang.Object

Provides the functionality to use and maintain XML files. This implementation reads the file and keeps all data in memory.
Each tag corresponds to a section, with the complete path to a tag and the tag's name itself as section name.

 <foo>
   <bar  attr="value" />
 </foo>
 

corresponds to the sections

• /foo/
• /foo/bar/

and one readable value.

getString("/foo/bar", "attr", null);

returns "value"
A speciality is the handling of duplicate tags:

 <foo>
   <bar  attr="value" />
   <bar  attr="other" />
 </foo>
 

Since there seems no way to have access to one of the "/foo/bar" tags, an autonumbering method is used, which adds an unqiue number to all duplicate tags. Better than guessing the assigned numbers, is to use the getSections() method which returns a Vector with all valid paths:

getSections("/foo/bar")

will return something like

/foo/bar#000000/
 /foo/bar#000001/

Using that paths enables the direct access again.
Last feature is a mechanism called 'access by name attribute'.

 <foo>
   <bar  name="joe" attr="value" />
   <bar  name="carl" attr="other" />
 </foo>
 

To access a named tag directly just use a special encoding:

getString("/foo/\\bar\\carl", "attr", null);

returns "other".
The tag name is escaped within in '\\' and the name value is added. This also works for nested named tags!
File parts with

• "<? ... >"
• "<! ... >" and
• "<!-- ... -->"

are ignored but kept for output.

Constructor Summary

XmlFile()
construct an XmlFile object without an file.

XmlFile(java.lang.String fileName)
Deprecated. use XmlFile() and readFile()

Method Summary

void	addComment(java.lang.String section, java.lang.String comment) Set the specified content element of the section as String.
void	clear() Remove all content from this instance.
void	clearSection(java.lang.String section) Clear all content and children from this section.
java.lang.String	createSection(java.lang.String section) Creates always a new section and returns its unique path.
void	dropSection(java.lang.String section) Drop the section and remov all content and children from this section.
void	flush() Write all internal data to the file.
java.util.Map	getAttributes(java.lang.String section) Return a map with all attributes: name->value.
java.lang.String	getContent(java.lang.String section) Get the specified content element of the section as String.
byte[]	getContentBytes(java.lang.String section) Get the complete content of the section as byte array.
java.util.Vector	getKeys(java.lang.String section) get all attribute names (keys) for a section in the given XML file.
java.util.Vector	getSections(java.lang.String path) Get all sections for the given XML file, matching the path String.
java.lang.String	getString(java.lang.String section, java.lang.String attribute, java.lang.String def) get a value for an attribute in the section for the given XML file.
void	read(java.io.InputStream is) Read and parse the specified intput stream.
void	readFile(java.lang.String fileName) read the specified xml file.
java.util.Iterator	sections(java.lang.String sectionName) Get an Iterator for the child sections.
void	setContent(java.lang.String section, java.lang.String content) add a comment to the section as String.
void	setFile(java.lang.String fileName) set a new file name.
void	setString(java.lang.String section, java.lang.String attribute, java.lang.String value) Set a value for an attribute in the section for the given XML file.
void	sort(java.lang.String section, java.lang.String order) Sort the entries by the specified order.
java.lang.String	toString() Displays the full XML content.
void	write(java.io.OutputStream os) Write the current XML file to given OutputStream.

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlFile

public XmlFile(java.lang.String fileName)

Deprecated. use XmlFile() and readFile()

construct an XmlFile object.

Parameters:

fileName - name of the used XML file

XmlFile

public XmlFile()

construct an XmlFile object without an file.

Method Detail

readFile

public void readFile(java.lang.String fileName)

read the specified xml file.

Parameters:

fileName - the file name

setFile

public void setFile(java.lang.String fileName)

set a new file name.

Parameters:

fileName - the new file name

clear

public void clear()

Remove all content from this instance.

read

public void read(java.io.InputStream is)

Read and parse the specified intput stream. Appends data to current instance.

Parameters:

is - n input stream.

flush

public void flush()

Write all internal data to the file.

write

public void write(java.io.OutputStream os)
           throws java.io.IOException

Write the current XML file to given OutputStream.

Parameters:

os - the OutputStream

Throws:

java.io.IOException - on error

getSections

public java.util.Vector getSections(java.lang.String path)

Get all sections for the given XML file, matching the path String. So "/foo/a" would match "/foo/all" and "/foo/any" but not "/foo/be". A path ending with '/' will return all contained elements.

Parameters:

path - the match String

Returns:

a vector of String with all matched section names.

getKeys

public java.util.Vector getKeys(java.lang.String section)

get all attribute names (keys) for a section in the given XML file.

Parameters:

section - the name of the section *

Returns:

a vector of String with all attribute names (keys)

getAttributes

public java.util.Map getAttributes(java.lang.String section)

Return a map with all attributes: name->value.

Parameters:

section - the name of the section.

Returns:

a map containing the attributes, or null if section does not exist.

getString

public java.lang.String getString(java.lang.String section,
                                  java.lang.String attribute,
                                  java.lang.String def)

get a value for an attribute in the section for the given XML file.

Parameters:

section - the name of the section

attribute - the name of the attribute

def - a default value, if the attribute was not found

Returns:

a String with the attributes value

See Also:

setString(java.lang.String, java.lang.String, java.lang.String)

setString

public void setString(java.lang.String section,
                      java.lang.String attribute,
                      java.lang.String value)

Set a value for an attribute in the section for the given XML file.

• If an attribute is added to a section which not exists, the section is created.
• If the attribute not yet exists, the attribute is created, otherwise the attributes value is replaced.
• If value == null the attribute is deleted.
• If attribute == null the section is deleted. Depending on value (==null) only the section itself is removed, or (!= null) itself and all children are deleted

.

Parameters:

section - the name of the section

attribute - the name of the attribute

value - the new key value

See Also:

getString(java.lang.String, java.lang.String, java.lang.String)

clearSection

public void clearSection(java.lang.String section)

Clear all content and children from this section.

Parameters:

section - a path to a XML tag

dropSection

public void dropSection(java.lang.String section)

Drop the section and remov all content and children from this section.

Parameters:

section - a path to a XML tag

getContentBytes

public byte[] getContentBytes(java.lang.String section)

Get the complete content of the section as byte array.

Parameters:

section - the name of a section.

Returns:

a byte array with the nth content or null if section is invalid.

getContent

public java.lang.String getContent(java.lang.String section)

Get the specified content element of the section as String. The content is the part between the tags.

   <sometag attr1="a" ...>CONTENT</sometag>
 

Parameters:

section - the name of a section.

Returns:

a String with the content or null if section is invalid.

See Also:

setContent(java.lang.String, java.lang.String)

addComment

public void addComment(java.lang.String section,
                       java.lang.String comment)

Set the specified content element of the section as String. If the section does not exist, it is created.

Parameters:

section - the name of a section.

comment - the new content.

setContent

public void setContent(java.lang.String section,
                       java.lang.String content)

add a comment to the section as String. This erases all current content! If the section does not exist, it is created.

Parameters:

section - the name of a section.

content - the new content.

See Also:

getContent(java.lang.String)

createSection

public java.lang.String createSection(java.lang.String section)

Creates always a new section and returns its unique path. E.g. if there are duplicate sections createSection("/foo/bar") might return a different path, "/foo/bar#000005/" so your created section is clearly identified.

Parameters:

section - the section to be created

Returns:

the unique section path to this section, always ending with a "/".

sort

public void sort(java.lang.String section,
                 java.lang.String order)

Sort the entries by the specified order.

Parameters:

section - the name of the section = a path to the xml tag.

order - the ordered child tag names which is applied to the existing children.

toString

public java.lang.String toString()

Displays the full XML content.

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()

sections

public java.util.Iterator sections(java.lang.String sectionName)

Get an Iterator for the child sections. The iterator returns a String containing the full path of the child section. so /foo/bar might iterate over /foo/bar/aaaa, foo/bar/bbbb, and so on

Parameters:

sectionName - the section name is an XML path like "/foo/bar"

Returns:

an Iterator for the child sections.