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

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

All Implemented Interfaces:

Iterable<Range>

public abstract class Match
extends Object
implements Iterable<Range>

The Match class uniquely identifies a particular element within a body of XHTML markup, and provides methods for performing every type of operation possible on any element. (Note that not all operations make sense for all elements.) It is created to represent an element selected by a CSS2 pattern applied to a body of markup by the CSSPatterns class, which returns the zero, or more, matches produced by its search in a Results object.

The Match class is abstract. Separate implementations handle the simple case of elements in immutable markup (ImmutableMatch) where none of the modification functions do anything but throw exceptions, and the complex case of elements in mutable markup (MutableMatch) where the modification functions actually work.

Author:

Chris W. Johnson

Constructor Summary

protected

Match()

Method Summary

Match	add(boolean AddBefore, Object NewStuff) Adds the supplied material before, or after, the element specified by this Match object.
Match	addAttribute(String AttrName, Object AttrValue) Adds an attribute to any markup element that is allowed to have attributes.
Match	addClass(String ClassList) Adds one or more class names to the "class" attribute of this markup element.
Match	addContent(boolean InsertBeforeExistingContent, Object Content) Inserts the supplied material into the content of this markup element, provided that this element is a start-tag, since no other elements can contain content (children).
static Match	create(Markup Markup, Range Item, int Index) Creates the type of Match object (ImmutableMatch} or {MutableMatch) appropriate to the type of Markup object (ImmutableMarkup or MutableMarkup) in which the specified element occurs.
void	delete() Deletes this markup element and any children it may have.
Match	deleteAttribute(String AttrName) Removes an attribute from this markup element.
Match	deleteClass(String ClassList) Deletes the supplied space-separated list of class names from the value of this markup element's "class" attribute.
Match	deleteContent() Deletes the content of this markup element, provided that this element is a start-tag, since no other elements can contain content (children).
Match	duplicate(boolean InsertDuplicateBefore) Makes a copy of this markup element, and any children it may have, then inserts the copy immediately before, or after, this element.
MarkupEnumeration	enumerate() Returns an enumeration of this subsection of the larger document.
MarkupEnumeration	enumerate(boolean ReturnEndTags) Returns an enumeration of this subsection of the larger document.
abstract boolean	equals(Object Other) Compares another object to this one, in order to determine if it refers to the same component of the same body of markup.
abstract boolean	exists() Returns true if the markup element referenced by this Match still exists, false otherwise.
abstract Range	get() Returns the markup element represented by this Match object.
Results	get(CSSPatterns Patterns) Searches this element, and its children, for matches with the specified CSS2 pattern(s).
Results	get(CSSPatterns Patterns, Results PrevResults) Searches this element, and its children, for matches with the specified CSS2 pattern(s).
Results	get(String Patterns) Searches this element, and its children, for matches with the specified CSS2 pattern(s).
Results	get(String Patterns, Results PrevResults) Searches this element, and its children, for matches with the specified CSS2 pattern(s).
Match	getAncestorOfType(String TagType) Get the most recent ancestor of a particular type, for example "form" or "label".
Results	getAncestors() Get a complete list of all the ancestors of the XHTML element referenced by this Match.
Results	getAncestors(boolean IncludeThis, Results PrevResults) Get a complete list of all the ancestors of the XHTML element referenced by this Match.
String	getAttribute(String AttrName) Returns the value of the named attribute, or null if there is no such attribute in this markup element.
Results	getCDATA() Returns a new Results object listing all of the CDATA (<![CDATA[ … ]]>) elements in this markup.
Results	getCDATA(Results PrevResults) Returns a new Results object listing all of the CDATA (<![CDATA[ … ]]>) elements in this markup.
Results	getComments() Returns a new Results object listing all of the comment (<!-- … -->) elements in this markup.
Results	getComments(Results PrevResults) Returns a new Results object listing all of the comment (<!-- … -->) elements in this markup.
Results	getContent() Return references to all of the children (but not grandchildren, etc.) of this markup element.
Results	getContent(Results PrevResults) Return references to all of the children (but not grandchildren, etc.) of this markup element.
Results	getDeclarations() Returns a new Results object listing all of the declaration (<! … >) elements in this markup.
Results	getDeclarations(Results PrevResults) Returns a new Results object listing all of the declaration (<! … >) elements in this markup.
double	getDouble() Invokes getText() and converts the String it returns into a double, if possible.
abstract int	getIndex() The index of this element in the markup that contains it.
long	getLong() Invokes getText() and converts the String it returns into a long, if possible.
abstract Markup	getMarkup() Returns the Markup object in which this match occurs.
Namespace	getNamespace() Returns the namespace of the XML element referenced by this match.
Match	getParent() Get the immediate parent of the XHTML element referenced by this Match.
String	getText() Returns the human-readable/-visible text, if any, that this element would contribute to the final, rendered document.
StringBuffer	getText(StringBuffer Buff) Returns the human-readable/-visible text, if any, that this element would contribute to the final, rendered document.
StringBuilder	getText(StringBuilder Buff) Returns the human-readable/-visible text, if any, that this element would contribute to the final, rendered document.
String	getType() Returns the type of the XML element referenced by this match.
boolean	hasAttribute(String AttrName) Returns true if this markup element includes the specified attribute.
boolean	hasAttributeOfValue(String AttrName, String AttrValue) Returns true if this markup element has an attribute of the specified name and value.
boolean	hasClass(String ClassList) Tests the "class" attribute of this element, if it has one, for the presence of the named class or classes.
int	hashCode()
boolean	hasNonEmptyAttribute(String AttrName) Returns true if this markup element includes the specified attribute, and the value of the attribute is of a non-zero length.
Match	insert(boolean InsertBefore, Object NewStuff) Deprecated. Use add(boolean, java.lang.Object) instead.
Iterator<Range>	iterator() Returns an Iterator for this subsection of the larger document.
Match	print() Prints a nicely formatted representation of this element, and any children it may possess, to System.out.
Match	replace(Object Replacement) Removes this element from the markup, and inserts the supplied replacement object in its place.
Match	setAttribute(String AttrName, Object AttrValue) Replaces the value of an existing attribute, or creates a new attribute, in any markup element that is allowed to have attributes.
Match	setClass(String ClassList) Replaces any existing value of the "class" attribute of this markup element with the supplied space-separated list of class names.
Match	setContent(Object Content) Replaces any existing contents of this markup element with the supplied material.
Results	toResults() Creates a Results object containing only this Match.
String	toString() Returns a String containing the XML markup for the element referenced by this Match.
String	toString(boolean ElementOnly) Returns a String containing the XML markup for the element referenced by this Match, optionally including any child elements, and the terminating "end" tag, if any.
Match	updateAttribute(String AttrName, Object AttrValue) Replaces the value of an existing attribute, but never creates a new attribute, in any markup element that is allowed to have attributes.
void	write(PrintWriter Out) Writes-out the XML markup element referenced by this Match object, including all child elements, and the terminating "end" tag, if any.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Match

protected Match()

Method Detail

create

public static Match create(Markup Markup,
                           Range Item,
                           int Index)

Creates the type of Match object (ImmutableMatch} or {MutableMatch) appropriate to the type of Markup object (ImmutableMarkup or MutableMarkup) in which the specified element occurs.

Parameters:

Markup - The Markup object in which the specified element is stored.

Item - The markup element to be represented by this class.

Index - The index of the markup element within the Markup object.

Returns:

A Match subclass uniquely identifying the specified markup element.

getMarkup

public abstract Markup getMarkup()

Returns the Markup object in which this match occurs. This will always be the same Markup object that was passed to the constructor.

Returns:

The Markup object in which this Match occurs.

getIndex

public abstract int getIndex()
                      throws NoSuchElementException

The index of this element in the markup that contains it. When the containing markup is immutable, this index is a constant, but when the markup is mutable, the index can change. In the latter case, this method verifies the index of the element, and corrects it if there's been a change.

Returns:

The index of this element within the markup.

Throws:

NoSuchElementException - If this element is no longer present in the markup.

get

public abstract Range get()
                   throws NoSuchElementException

Returns the markup element represented by this Match object.

Returns:

The markup element represented by this Match object.

Throws:

NoSuchElementException - If this element is no longer present in the markup.

toResults

public Results toResults()

Creates a Results object containing only this Match.

Returns:

A Results object containing only this Match.

duplicate

public Match duplicate(boolean InsertDuplicateBefore)
                throws TagException

Makes a copy of this markup element, and any children it may have, then inserts the copy immediately before, or after, this element.

Parameters:

InsertDuplicateBefore - true if the duplicate should be inserted before the item that was duplicated, false if it should be inserted after.

Returns:

A Match object identifying the duplicate markup element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

replace

public Match replace(Object Replacement)
              throws TagException

Removes this element from the markup, and inserts the supplied replacement object in its place. Refer to the documentation for MutableMarkup.insert for an explanation of how the Replacement object is handled.

Parameters:

Replacement - The material that will replace this element in the markup. See MutableMarkup.insert for details.

Returns:

A Match object identifying the material that replaced this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

add

public Match add(boolean AddBefore,
                 Object NewStuff)
          throws TagException

Adds the supplied material before, or after, the element specified by this Match object. If the element specified by this Match object has children, and the new material is to be inserted after this element, the new material is inserted immediately after this element's end-tag (for example: "</a>", "</div>" or "</p>").

Parameters:

AddBefore - true if the new material should be inserted before this element, false if it should be inserted after it.

NewStuff - The material that will be inserted before/after this element in the markup. See MutableMarkup.insert for details.

Returns:

A Match object identifying the inserted material.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

insert

public Match insert(boolean InsertBefore,
                    Object NewStuff)
             throws TagException

Deprecated. Use add(boolean, java.lang.Object) instead.

Inserts the supplied material before, or after, the element specified by this Match object. If the element specified by this Match object has children, and the new material is to be inserted after this element, the new material is inserted immediately after this element's end-tag (for example: "</a>", "</div>" or "</p>").

Parameters:

InsertBefore - true if the new material should be inserted before this element, false if it should be inserted after it.

NewStuff - The material that will be inserted before/after this element in the markup. See MutableMarkup.insert for details.

Returns:

A Match object identifying the material that replaced this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

delete

public void delete()
            throws TagException

Deletes this markup element and any children it may have.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

exists

public abstract boolean exists()

Returns true if the markup element referenced by this Match still exists, false otherwise. This is only relevant when the markup containing this Match is mutable.

Returns:

true if the markup element referenced by this Match still exists, false otherwise.

getType

public String getType()

Returns the type of the XML element referenced by this match.

Returns:

The type of the XML element, or an empty String if this match references something other than an element.

getNamespace

public Namespace getNamespace()

Returns the namespace of the XML element referenced by this match.

Returns:

The namespace of the XML element, or null if no namespace.

getDouble

public double getDouble()
                 throws NumberFormatException

Invokes getText() and converts the String it returns into a double, if possible.

Returns:

The numeric value represented by the text of the element, as a double.

Throws:

NumberFormatException - If the text of this element couldn't be interpreted as a floating-point number.

See Also:

Double.parseDouble(java.lang.String)

getLong

public long getLong()
             throws NumberFormatException

Invokes getText() and converts the String it returns into a long, if possible.

Returns:

The numeric value represented by the text of the element, as a long.

Throws:

NumberFormatException - If the text of this element couldn't be interpreted as an integer number.

See Also:

Long.parseLong(java.lang.String, int)

getText

public String getText()

Returns the human-readable/-visible text, if any, that this element would contribute to the final, rendered document.

Returns:

A String containing the text of the element, or an empty string if no such text was present.

getText

public StringBuffer getText(StringBuffer Buff)

Returns the human-readable/-visible text, if any, that this element would contribute to the final, rendered document.

Parameters:

Buff - StringBuffer to which the text will be appended.

Returns:

The StringBuffer that was passed-in as the Buff parameter.

getText

public StringBuilder getText(StringBuilder Buff)

Returns the human-readable/-visible text, if any, that this element would contribute to the final, rendered document.

Parameters:

Buff - StringBuilder to which the text will be appended.

Returns:

The StringBuilder that was passed-in as the Buff parameter.

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 sections.

getCDATA

public Results getCDATA(Results PrevResults)

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

Parameters:

PrevResults - The previous Results object in a call chain. This is the Results object that will be returned when the pop method is invoked on the new Results object returned by this method.

Returns:

A Results object containing matches for CDATA sections.

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.

getComments

public Results getComments(Results PrevResults)

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

Parameters:

PrevResults - The previous Results object in a call chain. This is the Results object that will be returned when the pop method is invoked on the new Results object returned by this method.

Returns:

A Results object containing matches for comment elements.

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.

getDeclarations

public Results getDeclarations(Results PrevResults)

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

Parameters:

PrevResults - The previous Results object in a call chain. This is the Results object that will be returned when the pop method is invoked on the new Results object returned by this method.

Returns:

A Results object containing matches for declaration elements.

getContent

public Results getContent()

Return references to all of the children (but not grandchildren, etc.) of this markup element.

Returns:

A Results object containin references to all of the children of this markup element.

getContent

public Results getContent(Results PrevResults)

Return references to all of the children (but not grandchildren, etc.) of this markup element.

Parameters:

PrevResults - The previous Results object in a call chain. This is the Results object that will be returned when the pop method is invoked on the new Results object returned by this method.

Returns:

A Results object containin references to all of the children of this markup element.

addContent

public Match addContent(boolean InsertBeforeExistingContent,
                        Object Content)
                 throws TagException

Inserts the supplied material into the content of this markup element, provided that this element is a start-tag, since no other elements can contain content (children). The supplied material may be inserted before the first child, or after the last.

Parameters:

InsertBeforeExistingContent - true if the new material should be inserted before the first child of this element, false if it should be inserted after the final child.

Content - The material that will be inserted before/after this element's content. See MutableMarkup.insert for details.

Returns:

A Match object identifying the inserted material.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

deleteContent

public Match deleteContent()
                    throws TagException

Deletes the content of this markup element, provided that this element is a start-tag, since no other elements can contain content (children).

Returns:

A Match object identifying this markup element. (Not the deleted material.)

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

setContent

public Match setContent(Object Content)
                 throws TagException

Replaces any existing contents of this markup element with the supplied material.

Parameters:

Content - The material that will replace this element's content. See MutableMarkup.insert for details.

Returns:

A Match object identifying this markup element. (Not the inserted material.)

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

hasClass

public boolean hasClass(String ClassList)
                 throws TagException

Tests the "class" attribute of this element, if it has one, for the presence of the named class or classes.

Parameters:

ClassList - The name of a class, or a space-separated list of class names.

Returns:

true if all of the named classes are present in the "class" attribute of this element, false otherwise.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

addClass

public Match addClass(String ClassList)
               throws TagException

Adds one or more class names to the "class" attribute of this markup element. If this markup element has no "class" attribute, one is created. Redundant additions of class names are detected and omitted, so duplicates will not be created. Calling addAttribute and supplying "class" as the attribute name has exactly the same effect as this method, but is less efficient.

Parameters:

ClassList - A space-separated list of class names.

Returns:

A Match object identifying this markup element. If this element was immutable, a mutable version of it will have been created, substitued into this markup (assuming the markup itself is mutable), and the Match returned will refer to the new mutable form of this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

setClass

public Match setClass(String ClassList)
               throws TagException

Replaces any existing value of the "class" attribute of this markup element with the supplied space-separated list of class names. Redundant additions of class names are detected and omitted, so duplicates will not be created. Calling setAttribute and supplying "class" as the attribute name has exactly the same effect as this method, but is less efficient.

Parameters:

ClassList - A space-separated list of class names.

Returns:

A Match object identifying this markup element. If this element was immutable, a mutable version of it will have been created, substitued into this markup (assuming the markup itself is mutable), and the Match returned will refer to the new mutable form of this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

deleteClass

public Match deleteClass(String ClassList)
                  throws TagException

Deletes the supplied space-separated list of class names from the value of this markup element's "class" attribute. Deleting class names that aren't actually present in the value of this markup element's "class" attribute is no problem. If you want to remove all class names from this element, use deleteAttribute and pass "class" as the attribute name.

Parameters:

ClassList - A space-separated list of class names.

Returns:

A Match object identifying this markup element. If this element was immutable, a mutable version of it will have been created, substitued into this markup (assuming the markup itself is mutable), and the Match returned will refer to the new mutable form of this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

hasAttributeOfValue

public boolean hasAttributeOfValue(String AttrName,
                                   String AttrValue)

Returns true if this markup element has an attribute of the specified name and value.

Parameters:

AttrName - Name of the attribute.

AttrValue - Value of the attribute.

Returns:

true if the attribute is present and is of the specified value, false otherwise.

hasAttribute

public boolean hasAttribute(String AttrName)

Returns true if this markup element includes the specified attribute.

Parameters:

AttrName - Name of the attribute.

Returns:

true if the attribute is present, false otherwise.

hasNonEmptyAttribute

public boolean hasNonEmptyAttribute(String AttrName)

Returns true if this markup element includes the specified attribute, and the value of the attribute is of a non-zero length. Otherwise, this method returns false.

Parameters:

AttrName - Name of the attribute.

Returns:

true if this markup element includes the specified attribute, and the value of the attribute is of a non-zero length, false otherwise.

getAttribute

public String getAttribute(String AttrName)

Returns the value of the named attribute, or null if there is no such attribute in this markup element.

Parameters:

AttrName - Name of the attribute.

Returns:

Value of the attribute, or null if no such attribute.

addAttribute

public Match addAttribute(String AttrName,
                          Object AttrValue)
                   throws TagException

Adds an attribute to any markup element that is allowed to have attributes. If the markup element already has an attribute of the specified name, the new value is appended to the existing value. Note that nothing clever is done when appending, such as placing spaces between the original value and the new material that is appended to it. Instead, this is a plain and simple append operation. Because of that, it is possible to use this method to, for instance, progressively build-up a URL in an "a" (anchor) element's "href" attribute. When appending is not desired, use the setAttribute method instead.

If the attribute name is "class", this method performs the same function as the addClass method, but somewhat less efficiently.

Parameters:

AttrName - Name of the attribute.

AttrValue - Value of a new attribute, or the string to be appended to the value of an existing attribute.

Returns:

A Match object identifying this markup element. If this element was immutable, a mutable version of it will have been created, substitued into this markup (assuming the markup itself is mutable), and the Match returned will refer to the new mutable form of this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

setAttribute

public Match setAttribute(String AttrName,
                          Object AttrValue)
                   throws TagException

Replaces the value of an existing attribute, or creates a new attribute, in any markup element that is allowed to have attributes. If the attribute name is "class", this method performs the same function as the setClass method, but somewhat less efficiently.

Parameters:

AttrName - Name of the attribute.

AttrValue - Value of the attribute.

Returns:

A Match object identifying this markup element. If this element was immutable, a mutable version of it will have been created, substitued into this markup (assuming the markup itself is mutable), and the Match returned will refer to the new mutable form of this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

updateAttribute

public Match updateAttribute(String AttrName,
                             Object AttrValue)
                      throws TagException

Replaces the value of an existing attribute, but never creates a new attribute, in any markup element that is allowed to have attributes. If the attribute name is "class", this method performs the same function as the setClass method, but somewhat less efficiently.

Parameters:

AttrName - Name of the attribute.

AttrValue - Value of the attribute.

Returns:

A Match object identifying this markup element. If this element was immutable, a mutable version of it will have been created, substitued into this markup (assuming the markup itself is mutable), and the Match returned will refer to the new mutable form of this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

deleteAttribute

public Match deleteAttribute(String AttrName)
                      throws TagException

Removes an attribute from this markup element.

Parameters:

AttrName - Name of the attribute.

Returns:

A Match object identifying this markup element. If this element was immutable, a mutable version of it will have been created, substitued into this markup (assuming the markup itself is mutable), and the Match returned will refer to the new mutable form of this element.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

iterator

public Iterator<Range> iterator()

Returns an Iterator for this subsection of the larger document. If this Match object specifies an empty tag, only that tag will be returned by this Iterator. If this Match object specifies a start tag, that tag and all of its children (including all "end" tags) will be returned by the Iterator.

Specified by:

iterator in interface Iterable<Range>

Returns:

An Iterator of this element and any children it may possess.

enumerate

public MarkupEnumeration enumerate()

Returns an enumeration of this subsection of the larger document. If this Match object specifies an empty tag, only that tag will be returned by this enumeration. If this Match object specifies a start tag, that tag and all of its children (including all "end" tags) will be enumerated.

Returns:

An enumeration of this element and any children it may possess.

enumerate

public MarkupEnumeration enumerate(boolean ReturnEndTags)

Returns an enumeration of this subsection of the larger document. If this Match object specifies a self-contained tag, only that tag will be returned by this enumeration. If this Match object specifies a start-tag, that tag and all of its children will be enumerated.

Parameters:

ReturnEndTags - Set to true if the MarkupEnumeration object that is returned should include end tags (example: "</a>") among the elements it enumerates. If false, end tags are transparently skipped-over.

Returns:

An enumeration of this element and any children it may possess.

get

public Results get(String Patterns)

Searches this element, and its children, for matches with the specified CSS2 pattern(s). If there are no matches, the Results object returned is empty.

Parameters:

Patterns - One or more CSS2 patterns to be applied to this element's children.

Returns:

A Results object containing a list of elements that matched the specified pattern(s), if any.

get

public Results get(CSSPatterns Patterns)

Searches this element, and its children, for matches with the specified CSS2 pattern(s). If there are no matches, the Results object returned is empty.

Parameters:

Patterns - One or more CSS2 patterns to be applied to this element's children.

Returns:

A Results object containing a list of elements that matched the specified pattern(s), if any.

get

public Results get(String Patterns,
                   Results PrevResults)

Searches this element, and its children, for matches with the specified CSS2 pattern(s). If there are no matches, the Results object returned is empty.

Parameters:

Patterns - One or more CSS2 patterns to be applied to this element's children.

PrevResults - The previous Results object in a call chain. This is the Results object that will be returned when the pop method is invoked on the new Results object returned by this method.

Returns:

A Results object containing a list of elements that matched the specified pattern(s), if any.

get

public Results get(CSSPatterns Patterns,
                   Results PrevResults)

Searches this element, and its children, for matches with the specified CSS2 pattern(s). If there are no matches, the Results object returned is empty.

Parameters:

Patterns - One or more CSS2 patterns to be applied to this element's children.

PrevResults - The previous Results object in a call chain. This is the Results object that will be returned when the pop method is invoked on the new Results object returned by this method.

Returns:

A Results object containing a list of elements that matched the specified pattern(s), if any.

getAncestors

public Results getAncestors()

Get a complete list of all the ancestors of the XHTML element referenced by this Match.

Returns:

A new Results object containing a list of the ancestors of this tag. The first item will be the immediate parent of this element, the last element will be the most distant ancestor.

getAncestors

public Results getAncestors(boolean IncludeThis,
                            Results PrevResults)

Get a complete list of all the ancestors of the XHTML element referenced by this Match.

Parameters:

IncludeThis - true if this Match should be included in the list, false otherwise.

PrevResults - The previous Results object in a call chain. This is the Results object that will be returned when the pop method is invoked on the new Results object returned by this method. Can be null.

Returns:

A new Results object containing a list of the ancestors of this tag. The first item will be the immediate parent of this element, the last element will be the most distant ancestor.

getAncestorOfType

public Match getAncestorOfType(String TagType)

Get the most recent ancestor of a particular type, for example "form" or "label".

Parameters:

TagType - The type of tag to look for amongst this element's ancestors.

Returns:

The most recent ancestor of the specified type.

getParent

public Match getParent()

Get the immediate parent of the XHTML element referenced by this Match.

Returns:

A Match referencing the immediate parent of the XHTML reference by this Match object.

print

public Match print()

Prints a nicely formatted representation of this element, and any children it may possess, to System.out.

Returns:

A reference to this Match instance.

equals

public abstract boolean equals(Object Other)

Compares another object to this one, in order to determine if it refers to the same component of the same body of markup. (Note that the subclasses that supply the implementations of this method, ImmutableMatch and MutableMatch, use very different means of testing for equality.)

Overrides:

equals in class Object

Parameters:

Other - Another object to be tested for equality with this object.

Returns:

true if the objects match, false otherwise.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Returns a String containing the XML markup for the element referenced by this Match. Child elements are not included.

Overrides:

toString in class Object

Returns:

The XML markup for this element.

See Also:

toString(boolean)

toString

public String toString(boolean ElementOnly)

Returns a String containing the XML markup for the element referenced by this Match, optionally including any child elements, and the terminating "end" tag, if any.

Parameters:

ElementOnly - true if nothing but this element should be represented in the String, or false if child elements and the terminating "end" tag, if present, should also be included in the String.

Returns:

This element's XML markup, represented as a String.

write

public void write(PrintWriter Out)
           throws IOException

Writes-out the XML markup element referenced by this Match object, including all child elements, and the terminating "end" tag, if any.

Parameters:

Out - The PrintWriter to which the markup should be written.

Throws:

IOException - If the PrintWriter had a problem.