edu.utexas.its.eis.tools.qwicap.template.xml
Class Markup

java.lang.Object
  edu.utexas.its.eis.tools.qwicap.template.xml.Markup

All Implemented Interfaces:

Cloneable, Iterable<Range>

Direct Known Subclasses:

ImmutableMarkup, MutableMarkup

public abstract class Markup
extends Object
implements Cloneable, Iterable<Range>

Markup represents a body of XML markup. The markup represented may be an entire XML document, or merely a self-contained fragment. In either case, well-formedness is required to the extent that all "start" tags must have matching "end" tags, and the "end" tags must be correctly ordered.

Author:

Chris W. Johnson

Constructor Summary

Markup()

Method Summary

void	checkHierarchy() Performs a simple verification of the tag hierarchy in the XHTML markup represented by this object.
abstract Match	createMatch(Range TheElement, int IndexOfElementInThisMarkup)
MarkupEnumeration	enumerate() Returns an enumeration for the elements in this markup.
Results	first() Returns a Results object containing a reference to the first start tag in the document.
Results	get(CSSPatterns CSSPatts) Performs a pattern match on this markup using the Cascading Style Sheets level 2 (CSS2) selector scheme, and returns a list of all elements that matched the pattern(s).
Range	get(int Index) Returns an element from this markup.
Results	get(String CSSPatterns) Performs a pattern match on this markup using the Cascading Style Sheets level 2 (CSS2) selector scheme, and returns a list of all elements that matched the pattern(s).
Results	getCDATA() Returns a new Results object listing all of the CDATA (<![CDATA[ … ]]>) elements in this markup.
abstract int	getChangeCount() Returns a monotonically increasing integer which is incremented every time a modification is made to the markup list.
abstract String	getCharacterSet() Returns the name of the character set in which this markup was encoded when it was read.
Results	getComments() Returns a new Results object listing all of the comment (<!-- … -->) elements in this markup.
abstract CSSPatterns	getCSSPatterns(String PatsStr) Retrieves a compiled version of the specified CSS pattern.
Results	getDeclarations() Returns a new Results object listing all of the declaration (<! … >) elements in this markup.
abstract ImmutableMarkup	getImmutable() If this markup is already immutable, this method does nothing, and returns a reference to this object.
abstract 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.
String	getMarkupName() Returns the name, if any, of this body of markup.
abstract MutableMarkup	getMutable() If this markup is already mutable, this method does nothing, and returns a reference to this object.
boolean	isEmpty() Returns true if this markup contains no elements.
Iterator<Range>	iterator() Returns an Iterator for the elements in this markup.
void	print() Prints this markup to System.out for convenience in debugging.
void	setMarkupName(String Name) Assigns an arbitrary name to this body of markup.
int	size() Returns the number of elements in this markup.
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 java.lang.Object

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

Constructor Detail

Markup

public Markup()

Method Detail

getCharacterSet

public abstract String getCharacterSet()

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.

Returns:

The name of the character set in which this markup was found to be encoded when it was read.

getImmutable

public abstract ImmutableMarkup getImmutable()
                                      throws TagException

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.

Returns:

An immutable version of this markup.

Throws:

TagException - If an immutable form of this markup could not be made available.

getMutable

public abstract MutableMarkup getMutable()
                                  throws TagException

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.

Returns:

A mutable version of this markup.

Throws:

TagException - If a mutable form of this markup could not be made available.

setMarkupName

public final void setMarkupName(String Name)

Assigns an arbitrary name to this body of markup. This name is purely for your reference, and has no functional significance; the only method that accesses it is getMarkupName. For markup loaded from a file, the name is typically set to the absolute path of the file. For markup loaded from a URL, the name is typically set to the URL.

Parameters:

Name - The arbitrary name to be assigned to this body of markup.

getMarkupName

public final String getMarkupName()

Returns the name, if any, of this body of markup. The name is arbitrary, but when markup is loaded from a file, or URL, the name is typically set to the file name, or URL, respectively.

Returns:

The name assigned to this body of markup, or null.

getList

public abstract 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. It returns the underlying List object that stores all of the elements of this markup.

Returns:

List object that stores all the elements in this markup. Do not modify this List.

See Also:

get(int Index)

getChangeCount

public abstract int getChangeCount()

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.

Returns:

An integer that is incremented each time the markup list is altered.

size

public final int size()

Returns the number of elements in this markup.

Returns:

The number of elements in this markup.

get

public final Range get(int Index)

Returns an element from this markup.

Parameters:

Index - The index number of the desired markup element.

Returns:

The markup element, a subclass of Range.

get

public final Results get(String CSSPatterns)

Performs a pattern match on this markup using the Cascading Style Sheets level 2 (CSS2) selector scheme, and returns a list of all elements that matched the pattern(s). See the Selectors section of the Cascading Style Sheets, level 2, CSS2 Specification. Note that those basic selectors can be used in complex combinations, and that this method supports all valid combinations, including coma-separated lists of independent selectors.

Parameters:

CSSPatterns - One or more CSS2 selector patterns represented as a String. See section 5.1 of the CSS2 specification for basic examples.

Returns:

A Results list containing references to each matching element in this markup.

get

public final Results get(CSSPatterns CSSPatts)

Performs a pattern match on this markup using the Cascading Style Sheets level 2 (CSS2) selector scheme, and returns a list of all elements that matched the pattern(s).

Parameters:

CSSPatts - One or more CSS2 selector pattern represented as a CSSPatterns instance.

Returns:

A Results list containing references to each matching element in this markup.

getDeclarations

public Results getDeclarations()

Returns a new Results object listing all of the declaration (<! … >) elements in this markup.

Returns:

A Results object containing matches for declaration elements.

getComments

public Results getComments()

Returns a new Results object listing all of the comment (<!-- … -->) elements in this markup.

Returns:

A Results object containing matches for comment elements.

getCDATA

public Results getCDATA()

Returns a new Results object listing all of the CDATA (<![CDATA[ … ]]>) elements in this markup.

Returns:

A Results object containing matches for CDATA elements.

first

public final Results first()

Returns a Results object containing a reference to the first start tag in the document.

Returns:

The first start tag in the document.

getCSSPatterns

public abstract CSSPatterns getCSSPatterns(String PatsStr)

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.

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.

createMatch

public abstract Match createMatch(Range TheElement,
                                  int IndexOfElementInThisMarkup)

isEmpty

public final boolean isEmpty()

Returns true if this markup contains no elements.

Returns:

true if this markup contains no elements, false otherwise.

enumerate

public final MarkupEnumeration enumerate()

Returns an enumeration for the elements in this markup.

Returns:

A MarkupEnumeration for the elements in this markup.

iterator

public Iterator<Range> iterator()

Returns an Iterator for the elements in this markup.

Specified by:

iterator in interface Iterable<Range>

Returns:

An iterator for the Range objects that comprise this markup.

checkHierarchy

public void checkHierarchy()
                    throws TagException

Performs a simple verification of the tag hierarchy in the XHTML markup represented by this object. It does nothing more than verify that every start-tag has a matching end-tag. This tells you that the XML is more-or-less correctly formed, which is sufficient to make this templating package happy, but does nothing more to verify well-formedness.

Throws:

TagException - If that tag hierarchy is incomplete or corrupt.

toString

public String toString()

Returns a String representing all the markup stored in this object.

Overrides:

toString in class Object

Returns:

A String representing all the markup stored in this object.

print

public void print()
           throws IOException

Prints this markup to System.out for convenience in debugging.

Throws:

IOException - If there was a problem writing to System.out.

See Also:

write(java.io.PrintWriter)

write

public PrintWriter write(PrintWriter Out)
                  throws IOException

Writes all of the markup stored in this object to a PrintWriter.

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.