|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object edu.utexas.its.eis.tools.qwicap.template.xml.Match
public abstract class Match
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.
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. |
Form |
toForm()
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. |
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 |
---|
protected Match()
Method Detail |
---|
public static Match create(Markup Markup, Range Item, int Index)
Match
object (ImmutableMatch
} or {MutableMatch
)
appropriate to the type of Markup
object (ImmutableMarkup
or MutableMarkup
) in which
the specified element occurs.
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.
Match
subclass uniquely identifying the specified markup element.public abstract Markup getMarkup()
Markup
object in which this match occurs. This will always be the same Markup
object that was passed to the constructor.
Markup
object in which this Match
occurs.public abstract int getIndex() throws NoSuchElementException
NoSuchElementException
- If this element is no longer present in the markup.public abstract Range get() throws NoSuchElementException
Match
object.
Match
object.
NoSuchElementException
- If this element is no longer present in the markup.public Results toResults()
Results
object containing only this Match
.
Results
object containing only this Match
.public Form toForm() throws FormNotFoundException
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.
Form
object for manipulating the "form" element
referenced by the first match in this Results
object.
FormNotFoundException
- If the this Match
instances does not refer to a "form"
element.MutableMarkup.getForm(FormDataSet)
,
Results.toForm()
public Match duplicate(boolean InsertDuplicateBefore) throws TagException
InsertDuplicateBefore
- true
if the duplicate should be inserted before the item that was
duplicated, false
if it should be inserted after.
Match
object identifying the duplicate markup element.
TagException
- If a problem is encountered with the manipulation of the markup.public Match replace(Object Replacement) throws TagException
MutableMarkup.insert
for an explanation of how the Replacement
object is handled.
Replacement
- The material that will replace this element in the markup. See
MutableMarkup.insert
for details.
Match
object identifying the material that replaced this element.
TagException
- If a problem is encountered with the manipulation of the markup.public Match add(boolean AddBefore, Object NewStuff) throws TagException
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>").
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.
Match
object identifying the inserted material.
TagException
- If a problem is encountered with the manipulation of the markup.public Match insert(boolean InsertBefore, Object NewStuff) throws TagException
add(boolean, java.lang.Object)
instead.
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>").
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.
Match
object identifying the material that replaced this element.
TagException
- If a problem is encountered with the manipulation of the markup.public void delete() throws TagException
TagException
- If a problem is encountered with the manipulation of the markup.public abstract boolean exists()
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.
true
if the markup element referenced by this Match
still exists, false
otherwise.public String getType()
String
if this match
references something other than an element.public Namespace getNamespace()
null
if no namespace.public double getDouble() throws NumberFormatException
getText()
and converts the String
it returns into a double
, if possible.
double
.
NumberFormatException
- If the text of this element couldn't be interpreted as a floating-point number.Double.parseDouble(java.lang.String)
public long getLong() throws NumberFormatException
getText()
and converts the String
it returns into a long
, if possible.
long
.
NumberFormatException
- If the text of this element couldn't be interpreted as an integer number.Long.parseLong(java.lang.String, int)
public String getText()
String
containing the text of the element, or an empty string if
no such text was present.public StringBuffer getText(StringBuffer Buff)
Buff
- StringBuffer
to which the text will be appended.
StringBuffer
that was passed-in as the Buff parameter.public StringBuilder getText(StringBuilder Buff)
Buff
- StringBuilder
to which the text will be appended.
StringBuilder
that was passed-in as the Buff parameter.public Results getCDATA()
Results
object listing all of the CDATA (<![CDATA[ … ]]>)
elements in this markup.
Results
object containing matches for CDATA sections.public Results getCDATA(Results PrevResults)
Results
object listing all of the CDATA (<![CDATA[ … ]]>)
elements in this markup.
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.
Results
object containing matches for CDATA sections.public Results getComments()
Results
object listing all of the comment (<!-- … -->)
elements in this markup.
Results
object containing matches for comment elements.public Results getComments(Results PrevResults)
Results
object listing all of the comment (<!-- … -->)
elements in this markup.
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.
Results
object containing matches for comment elements.public Results getDeclarations()
Results
object listing all of the declaration (<! … >)
elements in this markup.
Results
object containing matches for declaration elements.public Results getDeclarations(Results PrevResults)
Results
object listing all of the declaration (<! … >)
elements in this markup.
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.
Results
object containing matches for declaration elements.public Results getContent()
Results
object containin references to all of the children of
this markup element.public Results getContent(Results PrevResults)
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.
Results
object containin references to all of the children of
this markup element.public Match addContent(boolean InsertBeforeExistingContent, Object Content) throws TagException
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.
Match
object identifying the inserted material.
TagException
- If a problem is encountered with the manipulation of the markup.public Match deleteContent() throws TagException
Match
object identifying this markup element. (Not the deleted
material.)
TagException
- If a problem is encountered with the manipulation of the markup.public Match setContent(Object Content) throws TagException
Content
- The material that will replace this element's content. See
MutableMarkup.insert
for details.
Match
object identifying this markup element. (Not the inserted
material.)
TagException
- If a problem is encountered with the manipulation of the markup.public boolean hasClass(String ClassList) throws TagException
ClassList
- The name of a class, or a space-separated list of class names.
true
if all of the named classes are present in the "class"
attribute of this element, false
otherwise.
TagException
- If a problem is encountered with the manipulation of the markup.public Match addClass(String ClassList) throws TagException
addAttribute
and supplying "class" as the attribute name has exactly
the same effect as this method, but is less efficient.
ClassList
- A space-separated list of class names.
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.
TagException
- If a problem is encountered with the manipulation of the markup.public Match setClass(String ClassList) throws TagException
setAttribute
and supplying "class" as the attribute name has exactly the same effect
as this method, but is less efficient.
ClassList
- A space-separated list of class names.
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.
TagException
- If a problem is encountered with the manipulation of the markup.public Match deleteClass(String ClassList) throws TagException
deleteAttribute
and
pass "class" as the attribute name.
ClassList
- A space-separated list of class names.
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.
TagException
- If a problem is encountered with the manipulation of the markup.public boolean hasAttributeOfValue(String AttrName, String AttrValue)
true
if this markup element has an attribute of the specified name and value.
AttrName
- Name of the attribute.AttrValue
- Value of the attribute.
true
if the attribute is present and is of the specified value,
false
otherwise.public boolean hasAttribute(String AttrName)
true
if this markup element includes the specified attribute.
AttrName
- Name of the attribute.
true
if the attribute is present, false
otherwise.public boolean hasNonEmptyAttribute(String AttrName)
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
.
AttrName
- Name of the attribute.
true
if this markup element includes the specified attribute, and
the value of the attribute is of a non-zero length, false
otherwise.public String getAttribute(String AttrName)
null
if there is no such attribute in this markup element.
AttrName
- Name of the attribute.
null
if no such attribute.public Match addAttribute(String AttrName, Object AttrValue) throws TagException
setAttribute
method instead.
If the attribute name is "class", this method performs the same function as the addClass
method, but somewhat less efficiently.
AttrName
- Name of the attribute.AttrValue
- Value of a new attribute, or the string to be appended to the value of an
existing attribute.
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.
TagException
- If a problem is encountered with the manipulation of the markup.public Match setAttribute(String AttrName, Object AttrValue) throws TagException
setClass
method, but somewhat less efficiently.
AttrName
- Name of the attribute.AttrValue
- Value of the attribute.
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.
TagException
- If a problem is encountered with the manipulation of the markup.public Match updateAttribute(String AttrName, Object AttrValue) throws TagException
setClass
method, but somewhat less efficiently.
AttrName
- Name of the attribute.AttrValue
- Value of the attribute.
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.
TagException
- If a problem is encountered with the manipulation of the markup.public Match deleteAttribute(String AttrName) throws TagException
AttrName
- Name of the attribute.
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.
TagException
- If a problem is encountered with the manipulation of the markup.public Iterator<Range> iterator()
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
.
iterator
in interface Iterable<Range>
Iterator
of this element and any children it may possess.public MarkupEnumeration enumerate()
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.
public MarkupEnumeration enumerate(boolean ReturnEndTags)
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.
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.
public Results get(String Patterns)
Results
object returned is empty.
Patterns
- One or more CSS2 patterns to be applied to this element's children.
Results
object containing a list of elements that matched the
specified pattern(s), if any.public Results get(CSSPatterns Patterns)
Results
object returned is empty.
Patterns
- One or more CSS2 patterns to be applied to this element's children.
Results
object containing a list of elements that matched the
specified pattern(s), if any.public Results get(String Patterns, Results PrevResults)
Results
object returned is empty.
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.
Results
object containing a list of elements that matched the
specified pattern(s), if any.public Results get(CSSPatterns Patterns, Results PrevResults)
Results
object returned is empty.
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.
Results
object containing a list of elements that matched the
specified pattern(s), if any.public Results getAncestors()
Match
.
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.public Results getAncestors(boolean IncludeThis, Results PrevResults)
Match
.
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
.
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.public Match getAncestorOfType(String TagType)
TagType
- The type of tag to look for amongst this element's ancestors.
public Match getParent()
Match
.
Match
object.public Match print()
System.out
.
Match
instance.public abstract boolean equals(Object Other)
ImmutableMatch
and
MutableMatch
, use very different means of testing for equality.)
equals
in class Object
Other
- Another object to be tested for equality with this object.
true
if the objects match, false
otherwise.public int hashCode()
hashCode
in class Object
public String toString()
String
containing the XML markup for the element referenced by this Match
.
Child elements are not included.
toString
in class Object
toString(boolean)
public String toString(boolean ElementOnly)
String
containing the XML markup for the element referenced by this Match
,
optionally including any child elements, and the terminating "end" tag, if any.
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
.
String
.public void write(PrintWriter Out) throws IOException
Match
object, including all child elements, and
the terminating "end" tag, if any.
Out
- The PrintWriter
to which the markup should be written.
IOException
- If the PrintWriter
had a problem.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |