JXTA

net.jxta.impl.document
Class LiteXMLElement

java.lang.Object
  extended by net.jxta.impl.document.LiteXMLElement
All Implemented Interfaces:
Attributable, Element<LiteXMLElement>, TextElement<LiteXMLElement>, XMLElement<LiteXMLElement>
Direct Known Subclasses:
LiteXMLDocument

public class LiteXMLElement
extends Object
implements XMLElement<LiteXMLElement>

An element of a StructuredDocument. StructuredDocuments are made up of hierarchies of elements. LiteXMLElement is part of an implementation while makes use of XML-style document conventions, but without the overhead of a full parser.


Nested Class Summary
protected static class LiteXMLElement.charRange
          Defines a range of characters, probably within a string.
protected static class LiteXMLElement.tagRange
          A tagRange is a collection of char ranges useful for describing XML structures.
 
Field Summary
protected  LiteXMLDocument doc
          The document associated with this Element.
protected  LiteXMLElement.tagRange loc
          The portion of the source XML associated with this node
protected static boolean paranoidConsistencyChecking
          If true then every operation which modifies the state of the document will perform a consistency check.
protected  LiteXMLElement parent
          Identifies the element which is the parent of this element.
 
Constructor Summary
protected LiteXMLElement(LiteXMLDocument doc, LiteXMLElement.tagRange loc)
          Creates new LiteXMLElement
  LiteXMLElement(LiteXMLDocument doc, String name, String val)
          Creates new LiteElement
 
Method Summary
 String addAttribute(Attribute newAttrib)
          Adds an attribute with the given name and value.
 String addAttribute(String name, String value)
          Adds an attribute with the given name and value.
protected  void addChildTags(LiteXMLElement.charRange scanRange, LiteXMLElement addTo)
          Parse a charRange and add any tags found as content as children of a specified element.
protected  void adjustLocations(int beginningAt, int by)
          For this element and all its children adjust the location of its ranges by the amount specified.
 void appendChild(LiteXMLElement element)
          Add a child element to this element.
protected  boolean checkConsistency()
           
protected  StringBuilder decodeEscaped(StringBuilder target)
          Given a StringBuilder find all occurrences of escaped characters which must be decoded and convert them back to their non-escaped equivalents.
protected  void encodeEscaped(StringBuilder target)
          Given a StringBuilder find all occurrences of characters which must be escaped and convert them to their escaped equivalents.
 boolean equals(Object element)
          
 Attribute getAttribute(String name)
          Returns a single attribute which matches the name provided.
protected  LiteXMLElement.tagRange getAttributeLoc(String name, LiteXMLElement.charRange inRange)
          Returns the tagRange of the next attribute contained in the range provided.
 Enumeration<Attribute> getAttributes()
          Returns an enumerations of the attributes associated with this object.
 Enumeration<LiteXMLElement> getChildren()
          Returns an enumeration of the immediate children of this element.
 Enumeration<LiteXMLElement> getChildren(Object key)
          Returns an enumeration of the immediate children of this element whose name match the specified string.
 Enumeration<LiteXMLElement> getChildren(String name)
          Returns an enumeration of the immediate children of this element whose name match the specified string.
(package private)  LiteXMLDocument getDocument()
          The document we are a part of.
 String getKey()
          Get the name associated with an element.
 String getName()
          Get the name associated with an element.
 LiteXMLElement getParent()
          Get the parent element of this element.
 LiteXMLDocument getRoot()
          Get the root document element of the hierarchy this element belongs to.
protected  LiteXMLElement.tagRange getTagRanges(StringBuilder source, String tag, LiteXMLElement.charRange range)
          Given a source string, an optional tag and a range with in the source find either the tag specified or the next tag.
 String getTextValue()
          Get the value (if any) associated with an element.
protected  String getTextValue(boolean getEncoded, boolean trim)
          Get the value (if any) associated with an element.
 String getValue()
          Get the value (if any) associated with an element.
protected  void printNice(Writer into, int indent, boolean recurse)
          Write the contents of this element and optionally its children.
 String toString()
          

A toString implementation for debugging purposes.

 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

paranoidConsistencyChecking

protected static final transient boolean paranoidConsistencyChecking
If true then every operation which modifies the state of the document will perform a consistency check. This is a deadly performance killer but helps a lot in isolating bugs.

See Also:
Constant Field Values

doc

protected final transient LiteXMLDocument doc
The document associated with this Element.


parent

protected transient LiteXMLElement parent
Identifies the element which is the parent of this element. If this.parent == this then this element is the root of the document. If null == parent then this element has not yet been inserted into the document.


loc

protected transient LiteXMLElement.tagRange loc
The portion of the source XML associated with this node

Constructor Detail

LiteXMLElement

protected LiteXMLElement(LiteXMLDocument doc,
                         LiteXMLElement.tagRange loc)
Creates new LiteXMLElement

Parameters:
loc - The location of the element within the document.
doc - The LiteXMLDocument which is the root of the document.

LiteXMLElement

public LiteXMLElement(LiteXMLDocument doc,
                      String name,
                      String val)
Creates new LiteElement

Parameters:
doc - The LiteXMLDocument which is the root of the document.
name - The name of the element being created.
val - The value of the element being created or null if there is no content to the element.
Method Detail

equals

public boolean equals(Object element)

Overrides:
equals in class Object

toString

public String toString()

A toString implementation for debugging purposes.

Overrides:
toString in class Object

getRoot

public LiteXMLDocument getRoot()
Get the root document element of the hierarchy this element belongs to.

Specified by:
getRoot in interface Element<LiteXMLElement>
Specified by:
getRoot in interface TextElement<LiteXMLElement>
Specified by:
getRoot in interface XMLElement<LiteXMLElement>
Returns:
The root document element of this element's hierarchy.

getParent

public LiteXMLElement getParent()
Get the parent element of this element. If this Element has not been inserted into the Document then null is returned. If this element is the root element of the Document then it returns itself. ie., this == this.getParent().

Specified by:
getParent in interface Element<LiteXMLElement>
Returns:
The parent of this element. If the element has no parent then null will be returned. If the element is the root Element of the hierarchy then it will return itself.

getChildren

public Enumeration<LiteXMLElement> getChildren()
Returns an enumeration of the immediate children of this element.

Specified by:
getChildren in interface Element<LiteXMLElement>
Returns:
Enumeration containing all of the children of this element.

getName

public String getName()
Get the name associated with an element.

Specified by:
getName in interface TextElement<LiteXMLElement>
Returns:
A string containing the name of this element.

getKey

public String getKey()
Get the name associated with an element.

Specified by:
getKey in interface Element<LiteXMLElement>
Specified by:
getKey in interface TextElement<LiteXMLElement>
Returns:
A string containing the key of this element.

getValue

public String getValue()
Get the value (if any) associated with an element.

Specified by:
getValue in interface Element<LiteXMLElement>
Specified by:
getValue in interface TextElement<LiteXMLElement>
Returns:
A string containing the value of this element, if any, otherwise null.

appendChild

public void appendChild(LiteXMLElement element)
Add a child element to this element. The child element must be from the document as the element it is to be added to. Elements are created using either StructuredDocument.createElement(Object) or StructuredDocument.createElement(Object, Object).

Specified by:
appendChild in interface Element<LiteXMLElement>
Parameters:
element - The element to be added as a child.

getChildren

public Enumeration<LiteXMLElement> getChildren(Object key)
Returns an enumeration of the immediate children of this element whose name match the specified string.

Specified by:
getChildren in interface Element<LiteXMLElement>
Parameters:
key - The key which will be matched against.
Returns:
enumeration containing all of the children of this element.

getChildren

public Enumeration<LiteXMLElement> getChildren(String name)
Returns an enumeration of the immediate children of this element whose name match the specified string.

Specified by:
getChildren in interface TextElement<LiteXMLElement>
Parameters:
name - The name which will be matched against.
Returns:
An enumeration containing all of the children of this element.

getTextValue

public String getTextValue()
Get the value (if any) associated with an element.

Specified by:
getTextValue in interface TextElement<LiteXMLElement>
Returns:
A string containing the value of this element, if any, otherwise null.

getTextValue

protected String getTextValue(boolean getEncoded,
                              boolean trim)
Get the value (if any) associated with an element.

Parameters:
getEncoded - if true then the contents will be encoded such that the contents will not be interpreted as XML. see W3C XML 1.0 Specification ie. < -> < & -> &
trim - if true trims prefix and suffix white space
Returns:
A string containing the value of this element, if any, otherwise null.

printNice

protected void printNice(Writer into,
                         int indent,
                         boolean recurse)
                  throws IOException
Write the contents of this element and optionally its children. The writing is done to a provided java.io.Writer. The writing can optionally be indented.

Parameters:
into - The java.io.Writer that the output will be sent to.
indent - the number of tabs which will be inserted before each line.
recurse - if true then also print the children of this element.
Throws:
IOException - if an io error occurs

getTagRanges

protected LiteXMLElement.tagRange getTagRanges(StringBuilder source,
                                               String tag,
                                               LiteXMLElement.charRange range)
Given a source string, an optional tag and a range with in the source find either the tag specified or the next tag.

The search consists of 4 phases : 0. If no tag was specified, determine if a tag can be found and learn its name. 1. Search for the start of the named tag. 2. Search for the end tag. Each time we think we have found a tag which might be the end tag we make sure it is not the end tag of another element with the same name as our tag. 3. Calculate the position of the body of the tag given the locations of the start and end.

Parameters:
source - the string to search
tag - the tag to search for in the source string. If this tag is empty or null then we will search for the next tag.
range - describes the range of character locations in the source string to which the search will be limited.
Returns:
tagRange containing the ranges of the found tag.

addChildTags

protected void addChildTags(LiteXMLElement.charRange scanRange,
                            LiteXMLElement addTo)
Parse a charRange and add any tags found as content as children of a specified element. This process is repeated recursivly.

Parameters:
scanRange - the range to be parsed for sub-tags
addTo - the element to add any discovered children to.

adjustLocations

protected void adjustLocations(int beginningAt,
                               int by)
For this element and all its children adjust the location of its ranges by the amount specified.

Parameters:
beginningAt - adjust all locations which are at or past this location.
by - amount to adjust all matching locations.

decodeEscaped

protected StringBuilder decodeEscaped(StringBuilder target)
Given a StringBuilder find all occurrences of escaped characters which must be decoded and convert them back to their non-escaped equivalents.

Also does end of line folding per:

Parameters:
target - The StringBuilder which will be decoded.
Returns:
The decoded version of the StringBuilder.

encodeEscaped

protected void encodeEscaped(StringBuilder target)
Given a StringBuilder find all occurrences of characters which must be escaped and convert them to their escaped equivalents.

Parameters:
target - The StringBuilder which will be encoded in place.

getAttributes

public Enumeration<Attribute> getAttributes()
Returns an enumerations of the attributes associated with this object. Each element is of type Attribute.

Specified by:
getAttributes in interface Attributable
Returns:
Enumeration the attributes associated with this object.

getAttributeLoc

protected LiteXMLElement.tagRange getAttributeLoc(String name,
                                                  LiteXMLElement.charRange inRange)
Returns the tagRange of the next attribute contained in the range provided. The tag range returned consists of the startTag indicating the location of the name, body indicating the location of the value and endTag indicating the location of the final quote delimiter.

Parameters:
name - Name to match. null means match any name.
inRange - the limits of the locations to scan.
Returns:
tagRange containing the location of the next attribute

addAttribute

public String addAttribute(String name,
                           String value)
Adds an attribute with the given name and value. Some implementations may support only a single value for each distinct name. Others may support multiple values for each name. If the value being provided replaces some other value then that value is returned otherwise null is returned.

Specified by:
addAttribute in interface Attributable
Parameters:
name - name of the attribute.
value - value for the attribute.
Returns:
String containing previous value for this name if the value is being replaced otherwise null.

addAttribute

public String addAttribute(Attribute newAttrib)
Adds an attribute with the given name and value. Some implementations may support only a single value for each distinct name. Others may support multiple values for each name. If the value being provided replaces some other value then that value is returned otherwise null is returned.

Specified by:
addAttribute in interface Attributable
Parameters:
newAttrib - new attribute.
Returns:
String containing previous value for this name if the value is being replaced otherwise null.

getAttribute

public Attribute getAttribute(String name)
Returns a single attribute which matches the name provided. If no such named attribute exists then null is returned. For implementations of this interface which support multiple values for each name only the first value will be returned. To access all values for a name you must use getAttributes.

Specified by:
getAttribute in interface Attributable
Parameters:
name - the attribute name
Returns:
Attribute the attributes matching the given name.

checkConsistency

protected boolean checkConsistency()

getDocument

LiteXMLDocument getDocument()
The document we are a part of.

Returns:
The document we are a part of.

JXSE