edu.utexas.its.eis.tools.qwicap.template.css
Class Results

java.lang.Object
  edu.utexas.its.eis.tools.qwicap.template.css.Results

All Implemented Interfaces:

Iterable<Match>

public final class Results
extends Object
implements Iterable<Match>

The Results class exists to store references to the XML markup elements selected by CSS2 pattern searches, as well as references to the markup elements affected by the various operations that modify XML markup, such as the insert, delete, and duplicate operations which Results supplies. These references are referred to as "matches" and are represented by instances of the Match class. A Results object may contain any number of matches, including none. Every operation that can be performed on XML markup has a corresponding method in the Results class. Whenever such a method is invoked, the operation is individually applied to every match in that Results object. In cases where an operation can't logically be applied to some matches, the operation fails silenty and leaves untouched the markup referenced by those matches. Almost all operations return a new Results object containing matches relevant to the operation that was performed, so method chaining is not only possible, but very powerful.

Search Oriented Methods:

• get(String)
• get(CSSPatterns)

XML Element Oriented Methods:

• add(boolean, Object)
• addAfter(Object)
• addBefore(Object)
• copy()
• cut()
• delete()
• duplicate(boolean)
• duplicateAfter()
• duplicateBefore()
• extract()
• extractToMarkup()
• getAncestors()
• getCDATA()
• getComments()
• getDeclarations()
• getParent()
• getType()
• replace(java.lang.Object)
• toForm()
• toMarkup()

XML Element Content Oriented Methods:

• addContent(boolean, Object)
• addToStartOfContent(Object)
• addToEndOfContent(Object)
• deleteContent()
• getBigDecimal()
• getBigInteger()
• getBoolean()
• getByte()
• getContent()
• getDouble()
• getFloat()
• getInt()
• getLong()
• getShort()
• getText()
• setContent(Object)
• setContents(Object...)

XML Element Attribute Oriented Methods:

• addAttribute(String, Object)
• deleteAttribute(String)
• getAttribute(String)
• setAttribute(String, Object)
• setAttributes(Object...)
• updateAttribute(String, Object)

XML Element "class" Attribute Oriented Methods:

• addClass(String)
• deleteClass(String)
• setClass(String)

Filtering Operations on Results Objects:

• distinct()
• even()
• everyNth(int, int)
• first()
• last()
• nth(int)
• odd()

Logical Operations on Pairs of Results Objects:

• and()
• and(Results)
• or()
• or(Results)
• xor()
• xor(Results)

Method Invocation Chain Manipulation Methods:

• IF(boolean)
• IF_NOT_EMPTY()
• ELSE()
• ENDIF()
• pop()
• pop(int)

Building, Exploring, and Clearing Results Objects:

• addMatch(Match)
• addResults(Results)
• addToResults(Results)
• clear()
• get(int)
• isEmpty()
• iterator()
• notEmpty()
• nth(int)
• size()
• toString()

Author:

Chris W. Johnson

Constructor Summary

Results()
Instantiates an empty Results object.

Results(Results PrevResults)
Instantiates an empty Results object, which includes a reference to another "previous" Results object from which this Results object was, presumably, derived.

Method Summary

Results	add(boolean AddBefore, Object NewStuff) Inserts new material before, or after, each XML element referenced by the matches in this Results object.
Results	add(Match AMatch) Deprecated. Use addMatch instead.
Results	add(Results SomeResults) Deprecated. Use addResults instead.
Results	addAfter(Object NewStuff) Adds new material after each XML element referenced by the matches in this Results object.
Results	addAttribute(String AttrName, Object AttrValue) Adds an attribute to all of the applicable XML elements referenced by the matches in this Results object.
Results	addBefore(Object NewStuff) Adds new material before each XML element referenced by the matches in this Results object.
Results	addClass(String ClassList) Adds one or more CSS class names to the "class" attribute of all of the applicable XML elements referenced by the matches in this Results object.
Results	addContent(boolean InsertBeforeExistingContent, Object AdditionalContent) Adds to the content of each XML element referenced by the matches in this Results object.
Results	addContentAfter(Object AdditionalContent) Deprecated. Use addToEndOfContent instead.
Results	addContentAtEnd(Object AdditionalContent) Deprecated. Use addToEndOfContent instead.
Results	addContentAtStart(Object AdditionalContent) Deprecated. Use addToStartOfContent instead.
Results	addContentBefore(Object AdditionalContent) Deprecated. Use addToStartOfContent instead.
Results	addMatch(Match AMatch) Appends a Match to this Results object.
Results	addResults(Results SomeResults) Appends all of the matches in another Results object to this object.
Results	addTo(Results SomeResults) Deprecated. Use addToResults instead.
Results	addToEndOfContent(Object AdditionalContent) Adds new material to the end of the content of each XML element referenced by the matches in this Results object.
Results	addToResults(Results SomeResults) Appends all of the matches in this Results object to another Results object.
Results	addToStartOfContent(Object AdditionalContent) Adds new material at the start of the content of each XML element referenced by the matches in this Results object.
Results	and() Creates a new Results object containing all of the matches that are common to this Results object, and the previous Results object (as returned by pop()).
Results	and(Results B) Creates a new Results object containing all of the matches that are common to this Results object, and the supplied Results object, "B".
Results	clear() Removes all matches from this Results object.
ImmutableMarkup	copy() Creates a copy of all of the markup represented by the matches (and any children they may have) in this Results object.
ImmutableMarkup	cut() Removes all of the markup represented by the matches (and any children they may have) in this Results object, and returns it in a new ImmutableMarkup object.
Results	delete() Deletes each XML element (and any associated children) referenced by the matches in this Results object.
Results	deleteAttribute(String AttrName) Deletes the specified attribute from all of the applicable XML elements referenced by the matches in this Results object.
Results	deleteClass(String ClassList) Removes one or more CSS class names from the "class" attribute of all of the applicable XML elements referenced by the matches in this Results object.
Results	deleteContent() Deletes the contents of each XML element referenced by the matches in this Results object.
Results	distinct() Returns a new Results object which eliminates any redundant element references that may have been present in this Results object.
Results	duplicate(boolean InsertDuplicateBefore) Duplicates each XML element referenced by the matches in this Results object, and places the duplicate immediately before, or after, the referenced element.
Results	duplicateAfter() Duplicates each XML element referenced by the matches in this Results object, and places the duplicate immediately after the referenced element.
Results	duplicateBefore() Duplicates each XML element referenced by the matches in this Results object, and places the duplicate immediately before the referenced element.
Results	ELSE() Returns an empty Results object if the preceding IF invocation was passed true, and otherwise returns a Results object that is the same as the Results object on which the IF was invoked.
Results	ENDIF() Returns the Results object on which IF was invoked.
ResultsEnumerator	enumerate() Deprecated. Use iterator() instead.
Results	even() Returns every even-numbered Match in this Results object, beginning with the first Match (element 0).
Results	everyNth(int GroupSize, int GroupIndex) Conceptually divides the matches in this Results object into groups of a certain size, then returns a new Results object containing the Nth match from each group.
Results	extract() Moves all of the XML elements (children included) referenced by the matches in this Results object into a new MutableMarkup object, then returns a new Results object containing references to those elements in their new home.
MutableMarkup	extractToMarkup() Moves all of the XML elements (children included) referenced by the matches in this Results object into a new MutableMarkup object.
Results	first() Returns the first Match in this Results object as the sole element of a new Results object.
Results	get(CSSPatterns Patterns) Applies one or more CSS2 selector patterns to the subsections of XML referenced by the matches in this Results object.
Match	get(int Index) Returns the Match at the specified index in this Results object.
Results	get(String CSSPatternsStr) Applies one or more CSS2 selector pattern strings to the subsections of XML referenced by the matches in this Results object.
Results	getAncestors() Returns a complete list of the ancestors of each element referenced by the matches in this Results object.
String	getAttribute(String AttrName) Returns the value of the specified attribute from the first match in this Results object.
BigDecimal	getBigDecimal() Invokes getText() and converts the String it returns into a BigDecimal, if possible.
BigInteger	getBigInteger() Invokes getText() and converts the String it returns into a BigInteger, if possible.
boolean	getBoolean() Invokes getText() and converts the String it returns into a boolean, if possible.
byte	getByte() Invokes getText() and converts the String it returns into a byte, if possible.
Results	getCDATA() Returns a new Results object listing all of the CDATA (<![CDATA[ … ]]>) elements in the subsections of XML referenced by the matches in this Results object.
Results	getComments() Returns a new Results object listing all of the comment (<!-- … -->) elements in this markup.
Results	getContent() Returns a new Results object that references every child of every element referenced by this Results object.
Results	getDeclarations() 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.
float	getFloat() Invokes getText() and converts the String it returns into a float, if possible.
Form	getForm() Deprecated. Use toForm(), instead.
int	getInt() Invokes getText() and converts the String it returns into an int, if possible.
long	getLong() Invokes getText() and converts the String it returns into a long, if possible.
Results	getParent() Returns the parent element (if any) of each element referenced by the matches in this Results object.
short	getShort() Invokes getText() and converts the String it returns into a short, if possible.
String	getText() Returns the human-readable/-visible text, if any, that the elements referenced by this Results object would contribute to the final, rendered document.
String	getType() Returns the type of the first XML element in this Results objects.
Results	IF_NOT_EMPTY() If this Results object is not empty, a new Results object is returned that is the same as this Results object.
Results	IF(boolean B) Tests a boolean parameter: If it's true, a new Results object is returned that is the same as this Results object; if it's false, an empty Results object is returned.
Results	insert(boolean InsertBefore, Object NewStuff) Deprecated. Use add instead.
Results	insertAfter(Object NewStuff) Deprecated. Use addAfter instead.
Results	insertBefore(Object NewStuff) Deprecated. Use addBefore instead.
boolean	isEmpty() Returns true if there are no matches in this Results object.
Iterator<Match>	iterator() Returns an Iterator of the matches stored in this Results object.
Results	last() Returns the final Match in this Results object as the sole element of a new Results object.
boolean	notEmpty() Returns true if there is one, or more, matches in this Results object.
Results	nth(int Index) Returns the Match at the specified index in this Results object (the "Nth" Match) as the sole element of a new Results object.
Results	odd() Returns every odd-numbered Match in this Results object, beginning with the second Match (element 1).
Results	or() Creates a new Results object containing all of the matches that are present in either this Results object, or the previous Results object (as returned by pop()).
Results	or(Results B) Creates a new Results object containing all of the matches that are present in either this Results object, or the supplied Results object, "B".
Results	pop() Returns the Results object, if any, from which this instance was produced.
Results	pop(int PopCount) Returns the Nth Results object in this chain of Results objects; in effect this invokes the pop method N times and returns the result.
Results	print() Deprecated. Use toString() instead.
Results	print(String Prefix) Deprecated. Use toString() instead.
Results	replace(Object Replacement) Replaces each XML element referenced by the matches in this Results object with the supplied material.
Results	setAttribute(String AttrName, Object AttrValue) Sets the value of the specified attribute in all of the applicable XML elements referenced by the matches in this Results object.
Results	setAttributes(Object... AttrNamesAndValues) Sets the value of an arbitrary number of specified attributes in all of the applicable XML elements referenced by the matches in this Results object.
Results	setClass(String ClassList) Sets the value of the "class" attribute of all of the applicable XML elements referenced by the matches in this Results object.
Results	setContent(Object Value) Sets the content of each XML element referenced by the matches in this Results object.
Results	setContents(Object... SelectorsAndValues) Searches the content of each XML element referenced by the matches in this Results object using one or more CSS2 selector patterns, represented as String or a CSSPatterns object, then sets the content of the matching elements to the supplied value.
int	size() Returns the number of matches in this Results object.
Form	toForm() Returns a Form object for examining and/or manipulating the first XHTML "form" element (and the controls within it) that is found in this Results object.
MutableMarkup	toMarkup() Creates a MutableMarkup object containing all of the XML elements (and any associated children) referenced by the matches in this Results object.
String	toString() Returns a String representation of all of the XML elements (and any associated children) referenced by the matches in this Results object.
Results	updateAttribute(String AttrName, Object AttrValue) Sets the value of the specified attribute in all of the applicable XML elements referenced by the matches in this Results object.
Results	xor() Creates a new Results object containing all of the matches that are not common to this Results object and the previous Results object (as returned by pop()).
Results	xor(Results B) Creates a new Results object containing all of the matches that are not common to this and the supplied Results object, "B".

Methods inherited from class java.lang.Object

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

Constructor Detail

Results

public Results()

Instantiates an empty Results object.

Results

public Results(Results PrevResults)

Instantiates an empty Results object, which includes a reference to another "previous" Results object from which this Results object was, presumably, derived. The "previous" Results object can be explicitly accessed using the pop() method, and is implicitly utilized by various unitary operations like and(), or(), and xor().

Parameters:

PrevResults - A "previous" Results object from which this Results object was, presumably, derived.

Method Detail

iterator

public Iterator<Match> iterator()

Returns an Iterator of the matches stored in this Results object.

Specified by:

iterator in interface Iterable<Match>

Returns:

An Iterator of the matches stored in this Results object.

enumerate

@Deprecated
public ResultsEnumerator enumerate()

Deprecated. Use iterator() instead.

Returns an Enumeration of the matches stored in this Results object.

Returns:

An Enumeration of the matches stored in this Results object.

pop

public Results pop()

Returns the Results object, if any, from which this instance was produced.

Returns:

The Results object from which this instance was produced, or null, if there was no previous Results object.

pop

public Results pop(int PopCount)

Returns the N^th Results object in this chain of Results objects; in effect this invokes the pop method N times and returns the result.

Parameters:

PopCount - The number of pops to perform.

Returns:

The N^th Results object in this chain, or null if there weren't N Results objects in the chain.

size

public int size()

Returns the number of matches in this Results object.

Returns:

The number of matches in this Results object.

clear

public Results clear()

Removes all matches from this Results object. (The size method will subsequently return zero.)

Returns:

This Results object, with its contents removed.

isEmpty

public boolean isEmpty()

Returns true if there are no matches in this Results object.

Returns:

true if empty, false otherwise.

notEmpty

public boolean notEmpty()

Returns true if there is one, or more, matches in this Results object.

Returns:

true if one or more matches, false if empty.

addMatch

public Results addMatch(Match AMatch)

Appends a Match to this Results object.

Parameters:

AMatch - The Match to be appended to this list.

Returns:

This Results object.

add

@Deprecated
public Results add(Match AMatch)

Deprecated. Use addMatch instead.

Appends a Match to this Results object.

Parameters:

AMatch - The Match to be appended to this list.

Returns:

This Results object.

addResults

public Results addResults(Results SomeResults)

Appends all of the matches in another Results object to this object.

Parameters:

SomeResults - The Results object whose contents should be appended to the contents of this object.

Returns:

This Results object.

add

@Deprecated
public Results add(Results SomeResults)

Deprecated. Use addResults instead.

Appends all of the matches in another Results object to this object.

Parameters:

SomeResults - The Results object whose contents should be appended to the contents of this object.

Returns:

This Results object.

addToResults

public Results addToResults(Results SomeResults)

Appends all of the matches in this Results object to another Results object. This is the mirror image of addMatch.

Parameters:

SomeResults - The Results object to which this object's contents should be appended.

Returns:

This Results object.

addTo

@Deprecated
public Results addTo(Results SomeResults)

Deprecated. Use addToResults instead.

Appends all of the matches in this Results object to another Results object. This is the mirror image of addMatch.

Parameters:

SomeResults - The Results object to which this object's contents should be appended.

Returns:

This Results object.

or

public Results or()

Creates a new Results object containing all of the matches that are present in either this Results object, or the previous Results object (as returned by pop()). No Match will appear more than once in the new Results object.

Returns:

A new Results object containing all of the matches in this and the previous Results objects.

or

public Results or(Results B)

Creates a new Results object containing all of the matches that are present in either this Results object, or the supplied Results object, "B". No Match will appear more than once in the new Results object.

Parameters:

B - The other Results object.

Returns:

A new Results object containing all of the matches in this Results object and "B".

and

public Results and()

Creates a new Results object containing all of the matches that are common to this Results object, and the previous Results object (as returned by pop()).

Returns:

A new Results object containing all of the matches common to this and the previous Results objects.

and

public Results and(Results B)

Creates a new Results object containing all of the matches that are common to this Results object, and the supplied Results object, "B".

Parameters:

B - The other Results object.

Returns:

A new Results object containing all of the matches common to this Results object and "B".

xor

public Results xor()

Creates a new Results object containing all of the matches that are not common to this Results object and the previous Results object (as returned by pop()).

Returns:

A new Results object containing all of the matches not common to this and the previous Results objects.

xor

public Results xor(Results B)

Creates a new Results object containing all of the matches that are not common to this and the supplied Results object, "B".

Parameters:

B - The other Results object.

Returns:

A new Results object containing all of the matches not common to this and "B".

IF

public Results IF(boolean B)

Tests a boolean parameter: If it's true, a new Results object is returned that is the same as this Results object; if it's false, an empty Results object is returned. is returned. Note that nesting of IF, or IF_NOT_EMPTY, invocations is not supported.

Parameters:

B - boolean value to be tested.

Returns:

If the parameter was true, a Results object that is same as this object, otherwise an empty Results.

IF_NOT_EMPTY

public Results IF_NOT_EMPTY()

If this Results object is not empty, a new Results object is returned that is the same as this Results object. If this Results object is empty, an empty Results object is returned. Note that nesting of IF, or IF_NOT_EMPTY, invocations is not supported.

Returns:

If this Results is not empty, a Results object that is same as this object, otherwise an empty Results.

ELSE

public Results ELSE()

Returns an empty Results object if the preceding IF invocation was passed true, and otherwise returns a Results object that is the same as the Results object on which the IF was invoked.

Returns:

If the preceding IF tested true, an empty Results object, otherwise a Results object that is same as the Results object on which IF was invoked.

ENDIF

public Results ENDIF()

Returns the Results object on which IF was invoked.

Returns:

The Results object on which IF was invoked.

get

public Match get(int Index)

Returns the Match at the specified index in this Results object.

Parameters:

Index - The index number of the desired Match.

Returns:

The Match in this Results object.

Throws:

ArrayIndexOutOfBoundsException - If Index is too large or small.

See Also:

nth(int), everyNth(int, int), size(), iterator()

get

public Results get(String CSSPatternsStr)

Applies one or more CSS2 selector pattern strings to the subsections of XML referenced by the matches in this Results object.

Parameters:

CSSPatternsStr - CSS2 selector pattern(s).

Returns:

A Results object containing matches for each element selected by the CSS2 pattern.

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 the subsections of XML referenced by the matches in this Results object.

Returns:

A Results object containing matches for CDATA sections.

get

public Results get(CSSPatterns Patterns)

Applies one or more CSS2 selector patterns to the subsections of XML referenced by the matches in this Results object.

Parameters:

Patterns - CSS2 selector pattern(s) represented in their "compiled" form by a CSSPatterns object.

Returns:

A Results object containing matches for each element selected by the CSS2 pattern.

getAncestors

public Results getAncestors()

Returns a complete list of the ancestors of each element referenced by the matches in this Results object. This is generally useful only when there is a single match in this Results object.

Returns:

A new Results object containing a list of the ancestors of each element referenced by the matches in this Results object. If there is only one element referenced by this Results object, the first item in the Results object that is returned will be the immediate parent of the element, and the last element will be the most distant ancestor. If there is more than one element referenced by this Results object, this method probably isn't useful.

getParent

public Results getParent()

Returns the parent element (if any) of each element referenced by the matches in this Results object.

Returns:

A new Results object containing a reference to the parent element of each element referenced in this Results object.

getForm

@Deprecated
public Form getForm()

Deprecated. Use toForm(), instead.

Returns a Form object for examining and/or manipulating the XHTML "form" element (and the controls within it) that is referenced by the first match in this Results object. If you intend to modify the "form" element, or its contents, you should already be operating on MutableMarkup before invoking toForm. A mutable version of ImmutableMarkup is created trivially by merely invoking the Markup.getMutable() method.

Returns:

A Form object for manipulating the "form" element referenced by the first match in this Results object, or null if the Results object is either empty or its first match does not reference a "form" element.

See Also:

MutableMarkup.getForm(FormDataSet)

toForm

public Form toForm()
            throws FormNotFoundException

Returns a Form object for examining and/or manipulating the first XHTML "form" element (and the controls within it) that is found in this Results object. If you intend to modify the "form" element, or its contents, you should already be operating on MutableMarkup before invoking toForm. A mutable version of ImmutableMarkup is created trivially by merely invoking the Markup.getMutable() method.

Returns:

A Form object for manipulating the first "form" element found in this Results object.

Throws:

FormNotFoundException - If this Results object contains no "form" element.

See Also:

MutableMarkup.getForm(FormDataSet), Match.toForm()

distinct

public Results distinct()

Returns a new Results object which eliminates any redundant element references that may have been present in this Results object.

Returns:

A new Results object in which all of the element references are unique.

first

public Results first()

Returns the first Match in this Results object as the sole element of a new Results object. If there were no matches in this Results object, the new Results object is empty.

Returns:

A new Results object containing only the first Match in this Results object.

See Also:

last(), even(), odd()

last

public Results last()

Returns the final Match in this Results object as the sole element of a new Results object. If there were no matches in this Results object, the new Results object is empty.

Returns:

A new Results object containing only the final Match in this Results object.

See Also:

first(), odd(), even()

nth

public Results nth(int Index)

Returns the Match at the specified index in this Results object (the "N^th" Match) as the sole element of a new Results object. If there is no such element in this Results object, the new Results object is empty.

Parameters:

Index - The index number of the Match to be returned. (Greater than or equal to zero, less than size().)

Returns:

A new Results object containing the N^th Match in this Results object.

See Also:

get(int), size(), everyNth(int, int)

everyNth

public Results everyNth(int GroupSize,
                        int GroupIndex)

Conceptually divides the matches in this Results object into groups of a certain size, then returns a new Results object containing the Nth match from each group. For example, the even() convenience method is implemented as everyNth(2, 0) (return the match at index zero from every group of 2), and the odd() method is implemented as everyNth(2, 1) (return the match at index 1 from every group of 2).

Parameters:

GroupSize - The size of the groups into which the matches should be conceptually divided.

GroupIndex - The index of the match within each group of matches that is to be returned.

Returns:

A new Results object containing the requested Match objects.

even

public Results even()

Returns every even-numbered Match in this Results object, beginning with the first Match (element 0). If there were no matches in this Results object, the new Results object is empty. This method is useful for doing things like color-coding alternating rows of a table.

Returns:

A new Results object containing every even-numbered Match in this Results object, beginning with the first Match.

See Also:

odd(), everyNth(int, int), first(), last()

odd

public Results odd()

Returns every odd-numbered Match in this Results object, beginning with the second Match (element 1). If there were less than two matches in this Results object, the new Results object is empty. This method is useful for doing things like color-coding alternating rows of a table.

Returns:

A new Results object containing every odd-numbered Match in this Results object, beginning with the second Match.

See Also:

even(), everyNth(int, int), first(), last()

deleteContent

public Results deleteContent()
                      throws TagException

Deletes the contents of each XML element referenced by the matches in this Results object. For example, if there were a match for an "h1" element that looked like: "<h1>War and Peace</h1>", then calling deleteContent would reduce that "h1" element to: "<h1></h1>". Elements that have no content are not affected.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

setContent

public Results setContent(Object Value)
                   throws TagException

Sets the content of each XML element referenced by the matches in this Results object. For example, if there were a match for an "h1" element that looked like: "<h1>War and Peace</h1>", then calling setContent("Crime and Punishment") would change that "h1" element to: "<h1>Crime and Punishment</h1>". Elements that have no content are not affected.

Parameters:

Value - An object specifying the new content of the elements referenced by this Results object. Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing all of the matches in this Results object. If you would prefer a Results that references all of the content that was just set, follow your invocation of this method with an invocation of getContent.

Throws:

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

See Also:

getContent()

setContents

public Results setContents(Object... SelectorsAndValues)
                    throws TagException

Searches the content of each XML element referenced by the matches in this Results object using one or more CSS2 selector patterns, represented as String or a CSSPatterns object, then sets the content of the matching elements to the supplied value. This is equivalent to repeatedly chaining the method invocations: get(String) and setContent(Object). The various setContents methods are handy for doing things like setting the contents of all of the cells in a table row in one go.

Parameters:

SelectorsAndValues - An array of alternating CSS2 selector patterns, represented as String or CSSPatterns objects, and objects representing the content that should replace the existing content of the XML elements that match the preceding CSS2 selector pattern(s). There may be as many such selector/content pairs as desired.

Returns:

A new Results object containing matches for each element whose contents were set. If you would prefer a Results that references all of the content that was just set, follow your invocation of this method with an invocation of getContent.

Throws:

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

See Also:

getContent()

getType

public String getType()

Returns the type of the first XML element in this Results objects.

Returns:

The type of the first XML element in this Results object, or an empty string if none of the matches refer to XML elements.

getText

public String getText()

Returns the human-readable/-visible text, if any, that the elements referenced by this Results object would contribute to the final, rendered document. At present, this does not usually include the text contributed by "form" elements, and CSS style information (for example "display: none;") is not taken into account.

Returns:

The human-readable text of the elements referenced by this Results object, or an empty string if there was no such text.

getFloat

public float getFloat()
               throws NumberFormatException

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

Returns:

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

Throws:

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

See Also:

Float.parseFloat(String)

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(String)

getBigDecimal

public BigDecimal getBigDecimal()
                         throws NumberFormatException

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

Returns:

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

Throws:

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

See Also:

BigDecimal.BigDecimal(String)

getBoolean

public boolean getBoolean()

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

Returns:

true if the text of the element was "true" (case insensitive), false otherwise.

See Also:

Boolean.valueOf(String)

getByte

public byte getByte()
             throws NumberFormatException

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

Returns:

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

Throws:

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

See Also:

Byte.parseByte(String)

getShort

public short getShort()
               throws NumberFormatException

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

Returns:

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

Throws:

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

See Also:

Short.parseShort(String)

getInt

public int getInt()
           throws NumberFormatException

Invokes getText() and converts the String it returns into an int, if possible.

Returns:

The numeric value represented by the text of the element, as an int.

Throws:

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

See Also:

Integer.parseInt(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 a long.

See Also:

Long.parseLong(String)

getBigInteger

public BigInteger getBigInteger()
                         throws NumberFormatException

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

Returns:

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

Throws:

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

See Also:

BigInteger.BigInteger(String)

getContent

public Results getContent()

Returns a new Results object that references every child of every element referenced by this Results object. Note that only children are listed, not grandchildren and further descendants.

Returns:

A new Results object referencing every child of every element referenced by this Results object.

See Also:

setContent(java.lang.Object)

addToStartOfContent

public Results addToStartOfContent(Object AdditionalContent)
                            throws TagException

Adds new material at the start of the content of each XML element referenced by the matches in this Results object.

Parameters:

AdditionalContent - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing references to the content that was added to this markup.

Throws:

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

See Also:

addContent(boolean, Object)

addToEndOfContent

public Results addToEndOfContent(Object AdditionalContent)
                          throws TagException

Adds new material to the end of the content of each XML element referenced by the matches in this Results object.

Parameters:

AdditionalContent - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing references to the content that was added to this markup.

Throws:

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

See Also:

addContent(boolean, Object)

addContentAtStart

@Deprecated
public Results addContentAtStart(Object AdditionalContent)
                          throws TagException

Deprecated. Use addToStartOfContent instead.

Prepends new material to the content of each XML element referenced by the matches in this Results object.

Parameters:

AdditionalContent - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing references to the content that was added to this markup.

Throws:

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

addContentAtEnd

@Deprecated
public Results addContentAtEnd(Object AdditionalContent)
                        throws TagException

Deprecated. Use addToEndOfContent instead.

Appends new material to the content of each XML element referenced by the matches in this Results object.

Parameters:

AdditionalContent - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing references to the content that was added to this markup.

Throws:

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

addContentBefore

@Deprecated
public Results addContentBefore(Object AdditionalContent)
                         throws TagException

Deprecated. Use addToStartOfContent instead.

Prepends new material to the content of each XML element referenced by the matches in this Results object.

Parameters:

AdditionalContent - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing references to the content that was added to this markup.

Throws:

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

addContentAfter

@Deprecated
public Results addContentAfter(Object AdditionalContent)
                        throws TagException

Deprecated. Use addToEndOfContent instead.

Appends new material to the content of each XML element referenced by the matches in this Results object.

Parameters:

AdditionalContent - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing references to the content that was added to this markup.

Throws:

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

addContent

public Results addContent(boolean InsertBeforeExistingContent,
                          Object AdditionalContent)
                   throws TagException

Adds to the content of each XML element referenced by the matches in this Results object. For example, if there were a match for an "h1" element that looked like: "<h1>The Histories</h1>", then calling addContent(false, " by Herodotus") would change that "h1" element to: "<h1>The Histories by Herodotus</h1>".

Parameters:

InsertBeforeExistingContent - true to insert before the start of the existing content, false to insert after it.

AdditionalContent - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object containing references to the content that was added to this markup.

Throws:

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

See Also:

addToStartOfContent(Object), addToEndOfContent(Object)

duplicateBefore

public Results duplicateBefore()
                        throws TagException

Duplicates each XML element referenced by the matches in this Results object, and places the duplicate immediately before the referenced element. The children, if any, of those elements are also duplicated.

Returns:

A new Results object that references each duplicate.

Throws:

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

duplicateAfter

public Results duplicateAfter()
                       throws TagException

Duplicates each XML element referenced by the matches in this Results object, and places the duplicate immediately after the referenced element. The children, if any, of those elements are also duplicated.

Returns:

A new Results object that references each duplicate.

Throws:

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

duplicate

public Results duplicate(boolean InsertDuplicateBefore)
                  throws TagException

Duplicates each XML element referenced by the matches in this Results object, and places the duplicate immediately before, or after, the referenced element. The children, if any, of those elements are also duplicated.

Parameters:

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

Returns:

A new Results object that references each duplicate.

Throws:

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

replace

public Results replace(Object Replacement)
                throws TagException

Replaces each XML element referenced by the matches in this Results object with the supplied material.

Parameters:

Replacement - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object that references each replacement.

Throws:

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

addBefore

public Results addBefore(Object NewStuff)
                  throws TagException

Adds new material before each XML element referenced by the matches in this Results object.

Parameters:

NewStuff - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object that references the inserted material.

Throws:

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

addAfter

public Results addAfter(Object NewStuff)
                 throws TagException

Adds new material after each XML element referenced by the matches in this Results object.

Parameters:

NewStuff - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object that references the inserted material.

Throws:

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

insertBefore

@Deprecated
public Results insertBefore(Object NewStuff)
                     throws TagException

Deprecated. Use addBefore instead.

Inserts new material before each XML element referenced by the matches in this Results object.

Parameters:

NewStuff - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object that references the inserted material.

Throws:

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

insertAfter

@Deprecated
public Results insertAfter(Object NewStuff)
                    throws TagException

Deprecated. Use addAfter instead.

Inserts new material after each XML element referenced by the matches in this Results object.

Parameters:

NewStuff - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object that references the inserted material.

Throws:

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

insert

@Deprecated
public Results insert(boolean InsertBefore,
                                 Object NewStuff)
               throws TagException

Deprecated. Use add instead.

Inserts new material before, or after, each XML element referenced by the matches in this Results object.

Parameters:

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

NewStuff - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object that references the inserted material.

Throws:

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

add

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

Inserts new material before, or after, each XML element referenced by the matches in this Results object.

Parameters:

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

NewStuff - Any type of object is potentially suitable, see MutableMarkup.insert for details.

Returns:

A new Results object that references the inserted material.

Throws:

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

delete

public Results delete()
               throws TagException

Deletes each XML element (and any associated children) referenced by the matches in this Results object.

Returns:

A new, empty Results object.

Throws:

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

toString

public String toString()

Returns a String representation of all of the XML elements (and any associated children) referenced by the matches in this Results object.

Overrides:

toString in class Object

Returns:

String representation of all of the XML elements referenced by this Results object.

toMarkup

public MutableMarkup toMarkup()

Creates a MutableMarkup object containing all of the XML elements (and any associated children) referenced by the matches in this Results object. Note that the elements in this markup are the same elements that are present in the original markup, and changes to these elements in either body of markup will result in changes to these elements both bodies of markup.

Returns:

MutableMarkup object containing all of the XML elements referenced by this Results object.

See Also:

copy()

extract

public Results extract()
                throws TagException

Moves all of the XML elements (children included) referenced by the matches in this Results object into a new MutableMarkup object, then returns a new Results object containing references to those elements in their new home. This is useful for extracting a section of a document—typically a template—to get it out of the way until it is needed at a later time for use in the same document, or in a completely different one. Attempts to change the extracted markup by using lingering references to it in Match or Results objects will fail. However, if references have been retained to individal, mutable Range objects in the markup that was extracted, modifications to the extracted markup can be performed using them. That's not a normal usage mode, and you would probably know if you were keeping and using such references, so it's usually not worth worrying about, but if you need to be certain that nothing can modify the extracted markup through such lingering references, use the cut() method instead.

Returns:

A new Results object that references all of the extracted material in the new MutableMarkup object that was automatically created to contain it.

Throws:

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

See Also:

extractToMarkup(), cut()

extractToMarkup

public MutableMarkup extractToMarkup()
                              throws TagException

Moves all of the XML elements (children included) referenced by the matches in this Results object into a new MutableMarkup object. This is useful for extracting a section of a document—typically a template—to get it out of the way until it's needed at a later time for use in the same document, or in a completely different one. Attempts to change the extracted markup by using lingering references to it in Match or Results objects will fail. However, if references have been retained to individal, mutable Range objects in the markup that was extracted, modifications to the extracted markup can be performed using them. That's not a normal usage mode, and you would probably know if you were keeping and using such references, so it's usually not worth worrying about, but if you need to be certain that nothing can modify the extracted markup through such lingering references, use the cut() method instead.

Returns:

A new MutableMarkup object containing all of the extracted material.

Throws:

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

See Also:

extract(), cut()

copy

public ImmutableMarkup copy()
                     throws TagException

Creates a copy of all of the markup represented by the matches (and any children they may have) in this Results object. Changes to the original markup will not affect this copy.

Returns:

A new ImmutableMarkup object that is a copy of all of the markup represented by the matches in this Results object.

Throws:

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

See Also:

toMarkup()

cut

public ImmutableMarkup cut()
                    throws TagException

Removes all of the markup represented by the matches (and any children they may have) in this Results object, and returns it in a new ImmutableMarkup object. Changes to the original markup will not affect this copy.

Returns:

A new MutableMarkup object that holds all of the markup represented by the matches in this Results object.

Throws:

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

See Also:

extractToMarkup(), extract()

addClass

public Results addClass(String ClassList)
                 throws TagException

Adds one or more CSS class names to the "class" attribute of all of the applicable XML elements referenced by the matches in this Results object. The "class" attribute will be created, as necessary. Duplicate class names are detected and omitted, so there's no need to worry about redundancy.

Parameters:

ClassList - Space-separated list of class names.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

See Also:

setClass(String)

setClass

public Results setClass(String ClassList)
                 throws TagException

Sets the value of the "class" attribute of all of the applicable XML elements referenced by the matches in this Results object. The "class" attribute will be created, as necessary.

Parameters:

ClassList - Space-separated list of class names.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

See Also:

addClass(String)

deleteClass

public Results deleteClass(String ClassList)
                    throws TagException

Removes one or more CSS class names from the "class" attribute of all of the applicable XML elements referenced by the matches in this Results object. If the "class" attribute becomes empty, it will be omitted from the resulting markup.

Parameters:

ClassList - Space-separated list of class names.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

getAttribute

public String getAttribute(String AttrName)

Returns the value of the specified attribute from the first match in this Results object. If there are multiple matches in this Results object and you want the attribute value from each one, you will have to retrieve each match individually (using get(int) or iterator()) and invoke Match.getAttribute on each one.

Parameters:

AttrName - Name of the attribute.

Returns:

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

addAttribute

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

Adds an attribute to all of the applicable XML elements referenced by the matches in this Results object. If the attribute is already present, the new value is appended to the existing value. Where that appending behavior is not wanted, use setAttribute.

Parameters:

AttrName - Name of the attribute. (For the "class" attribute, addClass is more efficient.)

AttrValue - Value of the attribute. Can be null. If not null, the object's toString method is invoked.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

See Also:

setAttribute(String, Object)

updateAttribute

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

Sets the value of the specified attribute in all of the applicable XML elements referenced by the matches in this Results object. If the attribute does not exist, nothing happens. If it does exist, its value is replaced by the new value.

Parameters:

AttrName - Name of the attribute. (For the "class" attribute, setClass is more efficient.)

AttrValue - Value of the attribute. Can be null. If not null, the object's toString method is invoked.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

setAttribute

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

Sets the value of the specified attribute in all of the applicable XML elements referenced by the matches in this Results object. If the attribute does not exist, it is created. If it does exist, its value is replaced by the new value.

Parameters:

AttrName - Name of the attribute. (For the "class" attribute, setClass is more efficient.)

AttrValue - Value of the attribute. Can be null. If not null, the object's toString method is invoked.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

setAttributes

public Results setAttributes(Object... AttrNamesAndValues)
                      throws TagException

Sets the value of an arbitrary number of specified attributes in all of the applicable XML elements referenced by the matches in this Results object. If the attribute does not exist, it is created. If it does exist, its value is replaced by the new value.

Parameters:

AttrNamesAndValues - Array of name/value pairs specify the attributes to be set. The first element in each pair is the name, and the second is the value. The value can be null.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

deleteAttribute

public Results deleteAttribute(String AttrName)
                        throws TagException

Deletes the specified attribute from all of the applicable XML elements referenced by the matches in this Results object.

Parameters:

AttrName - Name of the attribute to be deleted.

Returns:

A new Results object containing all of the matches in this Results object.

Throws:

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

print

@Deprecated
public Results print()

Deprecated. Use toString() instead.

Prints the XML elements referenced by the matches in this Results object to System.out.

Returns:

This Results object, unaltered.

See Also:

toString()

print

@Deprecated
public Results print(String Prefix)

Deprecated. Use toString() instead.

Prints the XML elements referenced by the matches in this Results object to System.out with each line prefixed by the supplied string.

Parameters:

Prefix - A String to be used a prefix for each line of output. (Handy for indenting.)

Returns:

This Results object, unaltered.

See Also:

toString()