edu.utexas.its.eis.tools.qwicap.template.xml.immutable
Class ImmutableMarkup

java.lang.Object
  extended by edu.utexas.its.eis.tools.qwicap.template.xml.Markup
      extended by edu.utexas.its.eis.tools.qwicap.template.xml.immutable.ImmutableMarkup
All Implemented Interfaces:
Cloneable, Iterable<Range>
Direct Known Subclasses:
XMLDocument, XMLString

public class ImmutableMarkup
extends Markup

ImmutableMarkup represents a body of XML markup that cannot be altered in any way. The markup represented may be an entire XML document, or merely a fragment of XML. In either case, well-formedness is required to the extent that all "start" tags must have matching "end" tags.

Author:
Chris W. Johnson

Constructor Summary
ImmutableMarkup(char[] Chars)
          Parses a character array containing XML markup; either a well-formed fragment, or an entire XML document.
ImmutableMarkup(char[] Chars, int Index, int Limit)
          Parses a subsection of a character array containing XML markup; either a well-formed fragment, or an entire XML document.
ImmutableMarkup(MutableMarkup MDoc)
           
 
Method Summary
 ImmutableMarkup clone()
           
 Match createMatch(Range Element, int Index)
           
 int getChangeCount()
          Returns a monotonically increasing integer which is incremented every time a modification is made to the markup list.
 String getCharacterSet()
          Returns the name of the character set in which this markup was encoded when it was read.
 CSSPatterns getCSSPatterns(String PatsStr)
          Retrieves a compiled version of the specified CSS pattern.
 ImmutableMarkup getImmutable()
          If this markup is already immutable, this method does nothing, and returns a reference to this object.
 RangeList getList()
          This method is not part of the public API, but could not be hidden due to limitations in Java's access control system.
 MutableMarkup getMutable()
          If this markup is already mutable, this method does nothing, and returns a reference to this object.
 String toString()
          Returns a String representing all the markup stored in this object.
 PrintWriter write(PrintWriter Out)
          Writes all of the markup stored in this object to a PrintWriter.
 
Methods inherited from class edu.utexas.its.eis.tools.qwicap.template.xml.Markup
checkHierarchy, enumerate, first, get, get, get, getCDATA, getComments, getDeclarations, getMarkupName, isEmpty, iterator, print, setMarkupName, size
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ImmutableMarkup

public ImmutableMarkup(char[] Chars)
                throws TagException
Parses a character array containing XML markup; either a well-formed fragment, or an entire XML document.

Parameters:
Chars - The array of characters containing the XML markup to be parsed. The array is retained as the backing store for this body of markup, so under no circumstances should the contents of the array be modified after invoking this constructor.
Throws:
TagException - If there's a problem parsing the XML, verifying its tag hierarchy, or any number of related problems.

ImmutableMarkup

public ImmutableMarkup(char[] Chars,
                       int Index,
                       int Limit)
                throws TagException
Parses a subsection of a character array containing XML markup; either a well-formed fragment, or an entire XML document.

Parameters:
Chars - The array of characters containing the XML markup to be parsed. The array is retained as the backing store for this body of markup, so under no circumstances should the contents of the array be modified after invoking this constructor.
Index - The offset of the first character in the array that should be parsed.
Limit - The offset of the character immediately after the last character that should be parsed.
Throws:
TagException - If there's a problem parsing the XML, verifying its tag hierarchy, or any number of related problems.

ImmutableMarkup

public ImmutableMarkup(MutableMarkup MDoc)
                throws TagException
Throws:
TagException
Method Detail

getCharacterSet

public String getCharacterSet()
Description copied from class: Markup
Returns the name of the character set in which this markup was encoded when it was read. Once the markup has been read into memory, the characters are represented as standard Java (Unicode) characters. When written, they will be encoded in the character set in which they were originally encoded.

Specified by:
getCharacterSet in class Markup
Returns:
The name of the character set in which this markup was found to be encoded when it was read.

clone

public ImmutableMarkup clone()
                      throws CloneNotSupportedException
Overrides:
clone in class Object
Throws:
CloneNotSupportedException

getCSSPatterns

public CSSPatterns getCSSPatterns(String PatsStr)
Description copied from class: Markup
Retrieves a compiled version of the specified CSS pattern. Where possible, a previously compiled version of the pattern is retreived from an internal cache, to eliminate the expense of parsing the pattern and allocating the objects that describe it.

Specified by:
getCSSPatterns in class Markup
Parameters:
PatsStr - A CSS2 selector pattern string. See section 5.1 of the CSS2 specification for basic examples.
Returns:
A CSSPatterns object that implements the request search pattern.

getChangeCount

public final int getChangeCount()
Description copied from class: Markup
Returns a monotonically increasing integer which is incremented every time a modification is made to the markup list. This allows objects like MutableMatch to detect changes to the markup list that require them to re-verify the presence and location of the markup elements they reference. Users of this method should detect changes by testing a cached change count value for equality with the current change count value. Inequality means there's been a change. No further assumptions about the values should be made.

Specified by:
getChangeCount in class Markup
Returns:
An integer that is incremented each time the markup list is altered.

getList

public final RangeList getList()
Description copied from class: Markup
This method is not part of the public API, but could not be hidden due to limitations in Java's access control system. It returns the underlying List object that stores all of the elements of this markup.

Specified by:
getList in class Markup
Returns:
List object that stores all the elements in this markup. Do not modify this List.
See Also:
Markup.get(int Index)

createMatch

public final Match createMatch(Range Element,
                               int Index)
Specified by:
createMatch in class Markup

getImmutable

public ImmutableMarkup getImmutable()
                             throws TagException
Description copied from class: Markup
If this markup is already immutable, this method does nothing, and returns a reference to this object. If this markup is mutable, this method creates and returns an immutable representation of this mutable markup.

Specified by:
getImmutable in class Markup
Returns:
An immutable version of this markup.
Throws:
TagException - If an immutable form of this markup could not be made available.

getMutable

public final MutableMarkup getMutable()
Description copied from class: Markup
If this markup is already mutable, this method does nothing, and returns a reference to this object. If this markup is immutable, this method creates and returns a mutable copy of this immutable markup. Initially, all elements in the newly created MutableMarkup object are references to the immutable markup elements of the original ImmutableMarkup object, which makes the creation of the mutable copy of this markup extremely fast and memory efficient. Only the elements that are eventually modified are converted into mutable forms, and that conversion is performed both automatically, and transparently.

Specified by:
getMutable in class Markup
Returns:
A mutable version of this markup.

toString

public String toString()
Description copied from class: Markup
Returns a String representing all the markup stored in this object.

Overrides:
toString in class Markup
Returns:
A String representing all the markup stored in this object.

write

public PrintWriter write(PrintWriter Out)
                  throws IOException
Description copied from class: Markup
Writes all of the markup stored in this object to a PrintWriter.

Overrides:
write in class Markup
Parameters:
Out - The PrintWriter to which this markup will be written.
Returns:
The PrintWriter that was received as the Out parameter.
Throws:
IOException - If the supplied PrintWriter has any problem writing.