edu.utexas.its.eis.tools.qwicap.template.xml.mutable
Class MutableMarkup

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

All Implemented Interfaces:

Cloneable, Iterable<Range>

public final class MutableMarkup
extends Markup

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

Author:

Chris W. Johnson

Constructor Summary

MutableMarkup()

MutableMarkup(RangeList RangeList, String CharacterSet)

Method Summary

Match	add(Match Source) Add material at the end of this markup object.
Match	addAttribute(Match Target, String AttrName, Object AttrValue) Adds an attribute to any markup element that is allowed to have attributes.
Match	addClass(Match Target, String ClassList) Adds one or more classes to the specified tag, converting the tag from immutable to mutable, if necessary.
Match	addContent(Match Target, boolean InsertBeforeExistingContent, Object NewContent) Inserts the supplied material into the content of the specified markup element, provided that the element is a start-tag, or comment.
void	clear() Remove all material from this markup object.
MutableMarkup	clone()
int	convertSubmitButtonsToInputs() Converts all "button" controls of type "submit" to "input" controls of type "submit", in order to work around a hideous bug in Internet Explorer (Windows and Mac OS).
int	convertSubmitInputsToButtons() Converts all "input" controls of type "submit" that were "button" controls before convertSubmitButtonsToInputs() was invoked back into "button" controls of type "submit".
Match	createMatch(Range Element, int ElemIndex)
void	delete(Match Target) Deletes the specified material from this markup.
Match	deleteAttribute(Match Target, String AttrName) Removes an attribute from this markup element.
Match	deleteClass(Match Target, String ClassList) Delete from this markup element all of the specified classes.
Match	deleteContent(Match Target) Deletes the content of the specified markup element, provided that the element is a start-tag or comment.
Match	duplicate(Match Target, boolean InsertDuplicateBeforeTarget) Creates a duplicate of the specified material within this markup object and inserts it either immediately before, or after, the duplicated material.
MutableMarkup	embedFormDataSet(FormDataSet DataSet) Searches the document for a form that could have supplied a specified form data set, and, if found, embeds the values from the data set into the form.
MutableMarkup	embedFormDataSetIfPossible(FormDataSet DataSet) Searches the document for a form that could have supplied a specified form data set, and, if found, embeds the values from the data set into the form.
int	getChangeCount() Returns a monotonically increasing integer which is incremented every time a modification is made to the markup list.
String	getCharacterSet() Returns the name of the character set in which this markup was encoded when it was read.
CSSPatterns	getCSSPatterns(String PatsStr) Retrieves a compiled version of the specified CSS pattern.
Form	getForm(FormDataSet DataSet) Searches the document for a form that could have supplied a specified form data set, and returns a Form object for manipulating it.
ImmutableMarkup	getImmutable() If this markup is already immutable, this method does nothing, and returns a reference to this object.
RangeList	getList() This method is not part of the public API, but could not be hidden due to limitations in Java's access control system.
MutableMarkup	getMutable() If this markup is already mutable, this method does nothing, and returns a reference to this object.
static Characters	htmlDecode(Characters PotentiallyEncodedStr) Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.
static boolean	htmlDecode(Characters PotentiallyEncodedStr, StringBuffer Buff) Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.
static boolean	htmlDecode(Characters PotentiallyEncodedStr, StringBuilder Buff) Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.
static String	htmlDecode(String PotentiallyEncodedStr) Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.
static Characters	htmlEncode(Characters RawStr) Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).
static boolean	htmlEncode(Characters RawStr, StringBuffer Buff) Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).
static boolean	htmlEncode(Characters RawStr, StringBuilder Buff) Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).
static String	htmlEncode(String RawStr) Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).
Match	insert(Match Target, boolean InsertBefore, Object NewStuff) Inserts material into this markup before or after the element identified by the specified Match.
Match	replace(Match Target, Object Replacement) Replaces the specified material with other material.
Match	setAttribute(Match Target, 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.
MutableMarkup	setCharacterSet(String CharSetName)
Match	setClass(Match Target, String ClassList)
Match	setContent(Match Target, Object NewContent) Replaces any existing contents of the specified markup element with the supplied material.
Match	updateAttribute(Match Target, 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.

Methods inherited from class edu.utexas.its.eis.tools.qwicap.template.xml.Markup

checkHierarchy, enumerate, first, get, get, get, getCDATA, getComments, getDeclarations, getMarkupName, isEmpty, iterator, print, setMarkupName, size, toString, write

Methods inherited from class java.lang.Object

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

Constructor Detail

MutableMarkup

public MutableMarkup()

MutableMarkup

public MutableMarkup(RangeList RangeList,
                     String CharacterSet)

Method Detail

getMutable

public MutableMarkup getMutable()

Description copied from class: Markup

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

Specified by:

getMutable in class Markup

Returns:

A mutable version of this markup.

getImmutable

public ImmutableMarkup getImmutable()
                             throws TagException

Description copied from class: Markup

If this markup is already immutable, this method does nothing, and returns a reference to this object. If this markup is mutable, this method creates and returns an immutable representation of this mutable markup.

Specified by:

getImmutable in class Markup

Returns:

An immutable version of this markup.

Throws:

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

clone

public MutableMarkup clone()

Overrides:

clone in class Object

getCharacterSet

public String getCharacterSet()

Description copied from class: Markup

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

Specified by:

getCharacterSet in class Markup

Returns:

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

setCharacterSet

public MutableMarkup setCharacterSet(String CharSetName)
                              throws TagException

Throws:

TagException

getCSSPatterns

public CSSPatterns getCSSPatterns(String PatsStr)

Description copied from class: Markup

Retrieves a compiled version of the specified CSS pattern. Where possible, a previously compiled version of the pattern is retreived from an internal cache, to eliminate the expense of parsing the pattern and allocating the objects that describe it.

Specified by:

getCSSPatterns in class Markup

Parameters:

PatsStr - A CSS2 selector pattern string. See section 5.1 of the CSS2 specification for basic examples.

Returns:

A CSSPatterns object that implements the request search pattern.

embedFormDataSet

public MutableMarkup embedFormDataSet(FormDataSet DataSet)
                               throws QwicapException

Searches the document for a form that could have supplied a specified form data set, and, if found, embeds the values from the data set into the form. If such a form is not found, an exception is thrown.

Parameters:

DataSet - A form data set produced by a form in this document. If null, nothing happens.

Returns:

This MutableMarkup document (for convenience).

Throws:

QwicapException - If no form could be found in the document that could have supplied the specified form data set.

embedFormDataSetIfPossible

public MutableMarkup embedFormDataSetIfPossible(FormDataSet DataSet)

Searches the document for a form that could have supplied a specified form data set, and, if found, embeds the values from the data set into the form. If such a form is not found, nothing happens.

Parameters:

DataSet - A form data set produced by a form in this document. If null, nothing happens.

Returns:

This MutableMarkup document (for convenience).

getForm

public Form getForm(FormDataSet DataSet)
             throws QwicapException

Searches the document for a form that could have supplied a specified form data set, and returns a Form object for manipulating it.

Parameters:

DataSet - A form data set supplied by a form in this document.

Returns:

A Form object that can be used to manipulate the relevant form.

Throws:

FormNotFoundException - If no form could be found in the document that could have supplied the specified set of parameters.

QwicapException

See Also:

Results.toForm()

convertSubmitButtonsToInputs

public int convertSubmitButtonsToInputs()
                                 throws QwicapException

Converts all "button" controls of type "submit" to "input" controls of type "submit", in order to work around a hideous bug in Internet Explorer (Windows and Mac OS).

Returns:

The number of "button" elements that were converted into "input" elements.

Throws:

TagException - If there was a problem with the markup manipulation.

QwicapException

convertSubmitInputsToButtons

public int convertSubmitInputsToButtons()
                                 throws QwicapException

Converts all "input" controls of type "submit" that were "button" controls before convertSubmitButtonsToInputs() was invoked back into "button" controls of type "submit". In other words, this method undoes what convertSubmitButtonsToInputs() does.

Returns:

The number of "input" elements that were converted back into "button" elements.

Throws:

TagException - If there was a problem with the markup manipulation.

QwicapException

getChangeCount

public int getChangeCount()

Description copied from class: Markup

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

Specified by:

getChangeCount in class Markup

Returns:

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

getList

public RangeList getList()

Description copied from class: Markup

This method is not part of the public API, but could not be hidden due to limitations in Java's access control system. It returns the underlying List object that stores all of the elements of this markup.

Specified by:

getList in class Markup

Returns:

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

See Also:

Markup.get(int Index)

createMatch

public Match createMatch(Range Element,
                         int ElemIndex)

Specified by:

createMatch in class Markup

clear

public void clear()

Remove all material from this markup object.

add

public Match add(Match Source)

Add material at the end of this markup object.

Parameters:

Source - The material to be added to this markup object.

Returns:

The material added to this markup object.

duplicate

public Match duplicate(Match Target,
                       boolean InsertDuplicateBeforeTarget)

Creates a duplicate of the specified material within this markup object and inserts it either immediately before, or after, the duplicated material.

Parameters:

Target - The materail within this markup object to be duplicated.

InsertDuplicateBeforeTarget - true if the duplicate should be inserted before the original material, or false if it should be inserted after.

Returns:

The duplicate.

replace

public Match replace(Match Target,
                     Object Replacement)

Replaces the specified material with other material.

Parameters:

Target - The material to be replaced.

Replacement - The material to be added. See the insert description for details on how this object is handled.

Returns:

The material added.

delete

public void delete(Match Target)

Deletes the specified material from this markup.

Parameters:

Target - The material to be deleted.

addClass

public Match addClass(Match Target,
                      String ClassList)
               throws TagException

Adds one or more classes to the specified tag, converting the tag from immutable to mutable, if necessary.

Parameters:

Target - The tag to which the class is to be added.

ClassList - A space-separated list of classes to be added to the target tag.

Returns:

The tag to which the class was added.

Throws:

TagException - If there was a problem with the markup manipulation.

setClass

public Match setClass(Match Target,
                      String ClassList)
               throws TagException

Throws:

TagException

deleteClass

public Match deleteClass(Match Target,
                         String ClassList)
                  throws TagException

Delete from this markup element all of the specified classes.

Parameters:

Target - The markup element.

ClassList - A space-separated list of class names.

Returns:

A Match referencing the modified markup element.

Throws:

TagException - If there was a problem with the markup manipulation.

addAttribute

public Match addAttribute(Match Target,
                          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:

Target - The Match object identifying the markup element on which this method will operate.

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 there was a problem with the markup manipulation.

setAttribute

public Match setAttribute(Match Target,
                          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:

Target - The Match object identifying the markup element on which this method will operate.

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 there was a problem with the markup manipulation.

updateAttribute

public Match updateAttribute(Match Target,
                             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:

Target - The Match object identifying the markup element on which this method will operate.

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 there was a problem with the markup manipulation.

deleteAttribute

public Match deleteAttribute(Match Target,
                             String AttrName)
                      throws TagException

Removes an attribute from this markup element.

Parameters:

Target - The Match object identifying the markup element on which this method will operate.

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 there was a problem with the markup manipulation.

deleteContent

public Match deleteContent(Match Target)
                    throws TagException

Deletes the content of the specified markup element, provided that the element is a start-tag or comment.

Parameters:

Target - The Match object whose contents should be deleted.

Returns:

A Match object identifying the markup element whose content should be deleted. (Not the deleted material.)

Throws:

TagException - If there was a problem with the markup manipulation.

setContent

public Match setContent(Match Target,
                        Object NewContent)
                 throws TagException

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

Parameters:

Target - The Match object identifying the markup element on which this method will operate.

NewContent - 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 there was a problem with the markup manipulation.

addContent

public Match addContent(Match Target,
                        boolean InsertBeforeExistingContent,
                        Object NewContent)
                 throws TagException

Inserts the supplied material into the content of the specified markup element, provided that the element is a start-tag, or comment. The supplied material may be inserted before the existing contents, or after it.

Parameters:

Target - The Match object identifying the markup element on which this method will operate.

InsertBeforeExistingContent - true if the new material should be inserted before the existing content of this element, or false if it should be inserted after the existing content.

NewContent - 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 there was a problem with the markup manipulation.

insert

public Match insert(Match Target,
                    boolean InsertBefore,
                    Object NewStuff)

Inserts material into this markup before or after the element identified by the specified Match. If the element has children, and the insert is specified to take place after the element, the insertion is performed immediately after the element's end tag. The material to be inserted may be represented by any type of object. That object is handled according to the following rules:

1. If the new object is a String, a new mutable content object is created to represent the String, and that object is inserted into this markup.
2. If the new object is a Match, the markup element it represents, and any children of that element, are inserted into this markup. The "Cloning Rule" applies here.
3. If the new object is a Results, it is handled as if it were a sequence of Match objects being inserted (see above).
4. If the new object is a markup element (any subclass of Range) it is inserted into this markup. The "Cloning Rule" applies here.
5. If the new object is Markup, or any subclass thereof, every element in that Markup is inserted into this markup. The "Cloning Rule" applies here. Note, however, that because a Match object can reference only one markup element (and all of its children, by implication) the Match object returned by this method will reference only the first element in the inserted material. So, if the inserted material includes more than one parent tag, only the first parent and its children will be referenced by the Match object that is returned. (If this limitation ever becomes important, it can be fixed by having the high-level insert-related methods in the Results class test for instances of Markup, whereupon they would submit the top-level elements of the Markup as individual Match objects.)
6. If the new object is a Throwable, like the ever-popular class Exception, its message is inserted. If it does not have a message, the fully-qualified name of the Throwable object's class is inserted. In either case, the Throwable object's stack trace is then marked-up as an XHTML comment block and inserted, so the end-user will not see it, but the developer can view the page source to retrieve the stack trace.
7. If the new object is a Collection or an array, the contents will be interated through, with each element converted to a string, and commas inserted between elements. Whenever an element is found to be an array, or a Collection, the conversion process proceeds recursively, with the new material enclosed by brackets. (The elements of byte or Byte arrays, will be displayed as unsigned decimal quantities. This seemed like it would be more useful to most developers than displaying signed quantities.)
8. If the new object is not covered by any of the preceding rules, it is converted to a String by invoking its toString method, and the rule for inserting String objects is applied.

The Cloning Rule: No mutable element may exist more than once within a particular Markup object. If an attempt is made to add a mutable element to markup in which it is already present, the element is cloned, and the clone is added. (Note, by way of contrast, that the same mutable element is permitted to exist in any number of Markup objects, which is very efficient and convenient, but could lead to surprising results if the element is modified.)

Parameters:

Target - The location of the insert is relative to this element in this markup.

InsertBefore - If true, the new material is inserted before the Target element. If false, is inserted after Target. If Target has children, the insert is performed after its end tag.

NewStuff - The new material to be inserted. Any type of object is potentially valid.

Returns:

A Match object identifying the newly inserted material.

htmlEncode

public static String htmlEncode(String RawStr)

Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).

Parameters:

RawStr - The string to be encoded.

Returns:

A string with all reserved characters encoded, or the original string object if no encoding was necessary.

htmlDecode

public static String htmlDecode(String PotentiallyEncodedStr)

Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.

Parameters:

PotentiallyEncodedStr - The string to be decoded.

Returns:

A string with all HTML characters entities decoded into corresponding Unicode characters.

htmlEncode

public static Characters htmlEncode(Characters RawStr)

Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).

Parameters:

RawStr - The string to be encoded.

Returns:

A string with all reserved characters encoded, or the original string object if no encoding was necessary.

htmlDecode

public static Characters htmlDecode(Characters PotentiallyEncodedStr)

Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.

Parameters:

PotentiallyEncodedStr - The string to be decoded.

Returns:

A string with all HTML characters entities decoded into corresponding Unicode characters.

htmlEncode

public static boolean htmlEncode(Characters RawStr,
                                 StringBuffer Buff)

Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).

Parameters:

RawStr - The string to be encoded.

Buff - The StringBuffer to which the encoded string should be appended.

Returns:

A string with all reserved characters encoded, or the original string object if no encoding was necessary.

htmlDecode

public static boolean htmlDecode(Characters PotentiallyEncodedStr,
                                 StringBuffer Buff)

Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.

Parameters:

PotentiallyEncodedStr - The string to be decoded.

Buff - The StringBuffer to which the decoded string should be appended.

Returns:

A string with all HTML characters entities decoded into corresponding Unicode characters.

htmlEncode

public static boolean htmlEncode(Characters RawStr,
                                 StringBuilder Buff)

Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).

Parameters:

RawStr - The string to be encoded.

Buff - The StringBuffer to which the encoded string should be appended.

Returns:

A string with all reserved characters encoded, or the original string object if no encoding was necessary.

htmlDecode

public static boolean htmlDecode(Characters PotentiallyEncodedStr,
                                 StringBuilder Buff)

Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.

Parameters:

PotentiallyEncodedStr - The string to be decoded.

Buff - The StringBuffer to which the decoded string should be appended.

Returns:

A string with all HTML characters entities decoded into corresponding Unicode characters.