com.google.gwt.uibinder.rebind
Class XMLElement

java.lang.Object
  com.google.gwt.uibinder.rebind.XMLElement

public class XMLElement
extends java.lang.Object

A wrapper for Element that limits the way parsers can interact with the XML document, and provides some convenience methods.

The main function of this wrapper is to ensure that parsers can only read elements and attributes by 'consuming' them, which removes the given value. This allows for a natural hierarchy among parsers -- more specific parsers will run first, and if they consume a value, less-specific parsers will not see it.

Nested Class Summary

static interface	XMLElement.Interpreter<T> Callback interface used by consumeInnerHtml(Interpreter) and consumeChildElements(Interpreter).
static class	XMLElement.Location Represents the source location where the XMLElement was declared.
static interface	XMLElement.PostProcessingInterpreter<T> Extends XMLElement.Interpreter with a method to be called after all elements have been processed.

Method Summary

void	assertNoAttributes() Ensure that the receiver has no attributes left.
void	assertNoBody() Require that the receiver's body is empty of text and has no child nodes.
void	assertNoText() Require that the receiver's body is empty of text.
java.lang.String	consumeAttribute(java.lang.String name, JType type) Consumes the given attribute as a literal or field reference.
java.lang.String	consumeAttributeWithDefault(java.lang.String name, java.lang.String defaultValue, JType type) Consumes the given attribute as a literal or field reference.
java.lang.String	consumeAttributeWithDefault(java.lang.String name, java.lang.String defaultValue, JType[] types) Like consumeAttributeWithDefault(String, String, JType), but accomodates more complex type signatures.
java.lang.String	consumeBooleanAttribute(java.lang.String name) Convenience method for parsing the named attribute as a boolean value or reference.
java.lang.String	consumeBooleanAttribute(java.lang.String name, boolean defaultValue) Convenience method for parsing the named attribute as a boolean value or reference.
java.lang.Boolean	consumeBooleanConstantAttribute(java.lang.String name) Consumes the named attribute as a boolean expression.
java.lang.Iterable<XMLElement>	consumeChildElements() Consumes and returns all child elements.
java.util.Collection<XMLElement>	consumeChildElements(XMLElement.Interpreter<java.lang.Boolean> interpreter) Consumes and returns all child elements selected by the interpreter.
java.lang.String	consumeImageResourceAttribute(java.lang.String name) Convenience method for parsing the named attribute as an ImageResource value or reference.
java.lang.String	consumeInnerHtml(XMLElement.Interpreter<java.lang.String> interpreter) Consumes all child elements, and returns an HTML interpretation of them.
java.lang.String	consumeInnerHtml(XMLElement.PostProcessingInterpreter<java.lang.String> interpreter) Refines consumeInnerHtml(Interpreter) to handle PostProcessingInterpreter.
java.lang.String	consumeInnerText(XMLElement.PostProcessingInterpreter<java.lang.String> interpreter) Refines consumeInnerTextEscapedAsHtmlStringLiteral(Interpreter) to handle PostProcessingInterpreter.
java.lang.String	consumeInnerTextEscapedAsHtmlStringLiteral(XMLElement.Interpreter<java.lang.String> interpreter) Consumes all child text nodes, and asserts that this element held only text.
java.lang.String	consumeLengthAttribute(java.lang.String name) Convenience method for parsing the named attribute as a CSS length value.
java.lang.String	consumeOpeningTag() Consumes all attributes, and returns a string representing the entire opening tag.
java.lang.String[]	consumeRawArrayAttribute(java.lang.String name) Consumes the named attribute and parses it to an unparsed, unescaped array of Strings.
java.lang.String	consumeRawAttribute(java.lang.String name) Consumes the given attribute and returns its trimmed value, or null if it was unset.
java.lang.String	consumeRawAttribute(java.lang.String name, java.lang.String defaultValue) Consumes the given attribute and returns its trimmed value, or the given default value if it was unset.
java.lang.String	consumeRequiredAttribute(java.lang.String name, JType... types) Consumes the given required attribute as a literal or field reference.
java.lang.String	consumeRequiredDoubleAttribute(java.lang.String name) Convenience method for parsing the named required attribute as a double value or reference.
java.lang.String	consumeRequiredRawAttribute(java.lang.String name) Consumes the named attribute, or dies if it is missing.
XMLElement	consumeSingleChildElement() Consumes a single child element, ignoring any text nodes and throwing an exception if no child is found, or more than one child element is found.
java.lang.String[]	consumeStringArrayAttribute(java.lang.String name) Consumes the named attribute and parses it to an array of String expressions.
java.lang.String	consumeStringAttribute(java.lang.String name) Convenience method for parsing the named attribute as a String value or reference.
java.lang.String	consumeStringAttribute(java.lang.String name, java.lang.String defaultValue) Convenience method for parsing the named attribute as a String value or reference.
java.lang.String	consumeUnescapedInnerText() Returns the unprocessed, unescaped, raw inner text of the receiver.
XMLAttribute	getAttribute(int i) Get the attribute at the given index.
XMLAttribute	getAttribute(java.lang.String name) Get the attribute with the given name.
int	getAttributeCount()
java.lang.String	getClosingTag()
java.lang.String	getLocalName() Gets this element's local name (sans namespace prefix).
XMLElement.Location	getLocation()
java.lang.String	getNamespaceUri() Gets this element's namespace URI.
java.lang.String	getNamespaceUriForAttribute(java.lang.String fieldName)
XMLElement	getParent()
java.lang.String	getPrefix()
boolean	hasAttribute(java.lang.String name) Determines whether the element has a given attribute.
boolean	hasChildNodes()
java.lang.String	lookupPrefix(java.lang.String prefix)
void	setAttribute(java.lang.String name, java.lang.String value)
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

assertNoAttributes

public void assertNoAttributes()
                        throws UnableToCompleteException

Ensure that the receiver has no attributes left.

Throws:

UnableToCompleteException - if it does

assertNoBody

public void assertNoBody()
                  throws UnableToCompleteException

Require that the receiver's body is empty of text and has no child nodes.

Throws:

UnableToCompleteException - if it isn't

assertNoText

public void assertNoText()
                  throws UnableToCompleteException

Require that the receiver's body is empty of text.

Throws:

UnableToCompleteException - if it isn't

consumeAttribute

public java.lang.String consumeAttribute(java.lang.String name,
                                         JType type)
                                  throws UnableToCompleteException

Consumes the given attribute as a literal or field reference. The type parameter is required to determine how the value is parsed and validated.

Parameters:

name - the attribute's full name (including prefix)

type - the type this attribute is expected to provide

Returns:

the attribute's value as a Java expression, or null if it is not set

Throws:

UnableToCompleteException - on parse failure

consumeAttributeWithDefault

public java.lang.String consumeAttributeWithDefault(java.lang.String name,
                                                    java.lang.String defaultValue,
                                                    JType type)
                                             throws UnableToCompleteException

Consumes the given attribute as a literal or field reference. The type parameter is required to determine how the value is parsed and validated.

Parameters:

name - the attribute's full name (including prefix)

defaultValue - the value to @return if the attribute was unset

type - the type this attribute is expected to provide

Returns:

the attribute's value as a Java expression, or the given default if it was unset

Throws:

UnableToCompleteException - on parse failure

consumeAttributeWithDefault

public java.lang.String consumeAttributeWithDefault(java.lang.String name,
                                                    java.lang.String defaultValue,
                                                    JType[] types)
                                             throws UnableToCompleteException

Like consumeAttributeWithDefault(String, String, JType), but accomodates more complex type signatures.

Throws:

UnableToCompleteException

consumeBooleanAttribute

public java.lang.String consumeBooleanAttribute(java.lang.String name)
                                         throws UnableToCompleteException

Convenience method for parsing the named attribute as a boolean value or reference.

Returns:

an expression that will evaluate to a boolean value in the generated code, or null if there is no such attribute

Throws:

UnableToCompleteException - on unparseable value

consumeBooleanAttribute

public java.lang.String consumeBooleanAttribute(java.lang.String name,
                                                boolean defaultValue)
                                         throws UnableToCompleteException

Convenience method for parsing the named attribute as a boolean value or reference.

Parameters:

defaultValue - value to return if attribute was not set

Returns:

an expression that will evaluate to a boolean value in the generated code, or defaultValue if there is no such attribute

Throws:

UnableToCompleteException - on unparseable value

consumeBooleanConstantAttribute

public java.lang.Boolean consumeBooleanConstantAttribute(java.lang.String name)
                                                  throws UnableToCompleteException

Consumes the named attribute as a boolean expression. This will not accept {field.reference} expressions. Useful for values that must be resolved at compile time, such as generated annotation values.

Returns:

Boolean.TRUE, Boolean.FALSE, or null if no such attribute

Throws:

UnableToCompleteException - on unparseable value

consumeChildElements

public java.lang.Iterable<XMLElement> consumeChildElements()
                                                    throws UnableToCompleteException

Consumes and returns all child elements.

Throws:

UnableToCompleteException - if extra text nodes are found

consumeChildElements

public java.util.Collection<XMLElement> consumeChildElements(XMLElement.Interpreter<java.lang.Boolean> interpreter)
                                                      throws UnableToCompleteException

Consumes and returns all child elements selected by the interpreter. Note that text nodes are not elements, and so are not presented for interpretation, and are not consumed.

Parameters:

interpreter - Should return true for any child that should be consumed and returned by the consumeChildElements call

Throws:

UnableToCompleteException

consumeImageResourceAttribute

public java.lang.String consumeImageResourceAttribute(java.lang.String name)
                                               throws UnableToCompleteException

Convenience method for parsing the named attribute as an ImageResource value or reference.

Returns:

an expression that will evaluate toan ImageResource value in the generated code, or null if there is no such attribute

Throws:

UnableToCompleteException - on unparseable value

consumeInnerHtml

public java.lang.String consumeInnerHtml(XMLElement.Interpreter<java.lang.String> interpreter)
                                  throws UnableToCompleteException

Consumes all child elements, and returns an HTML interpretation of them. Trailing and leading whitespace is trimmed.

Each element encountered will be passed to the given Interpreter for possible replacement. Escaping is performed to allow the returned text to serve as a Java string literal used as input to a setInnerHTML call.

This call requires an interpreter to make sense of any special children. The odds are you want to use com.google.gwt.uibinder.elementparsers.templates.parsers.HtmlInterpreter for an HTML value, or com.google.gwt.uibinder.elementparsers.templates.parsers.TextInterpreter for text.

Parameters:

interpreter - Called for each element, expected to return a string replacement for it, or null if it should be left as is

Throws:

UnableToCompleteException

consumeInnerHtml

public java.lang.String consumeInnerHtml(XMLElement.PostProcessingInterpreter<java.lang.String> interpreter)
                                  throws UnableToCompleteException

Refines consumeInnerHtml(Interpreter) to handle PostProcessingInterpreter.

Throws:

UnableToCompleteException

consumeInnerText

public java.lang.String consumeInnerText(XMLElement.PostProcessingInterpreter<java.lang.String> interpreter)
                                  throws UnableToCompleteException

Refines consumeInnerTextEscapedAsHtmlStringLiteral(Interpreter) to handle PostProcessingInterpreter.

Throws:

UnableToCompleteException

consumeInnerTextEscapedAsHtmlStringLiteral

public java.lang.String consumeInnerTextEscapedAsHtmlStringLiteral(XMLElement.Interpreter<java.lang.String> interpreter)
                                                            throws UnableToCompleteException

Consumes all child text nodes, and asserts that this element held only text. Trailing and leading whitespace is trimmed, and escaped for use as a string literal. Notice that HTML entities in the text are also escaped--is this a source of errors?

This call requires an interpreter to make sense of any special children. The odds are you want to use com.google.gwt.uibinder.elementparsers.templates.parsers.TextInterpreter

Throws:

UnableToCompleteException - If any elements present are not consumed by the interpreter

consumeLengthAttribute

public java.lang.String consumeLengthAttribute(java.lang.String name)
                                        throws UnableToCompleteException

Convenience method for parsing the named attribute as a CSS length value.

Returns:

a (double, Unit) pair literal, an expression that will evaluate to such a pair in the generated code, or null if there is no such attribute

Throws:

UnableToCompleteException - on unparseable value

consumeOpeningTag

public java.lang.String consumeOpeningTag()

Consumes all attributes, and returns a string representing the entire opening tag. E.g., "

"

consumeRawArrayAttribute

public java.lang.String[] consumeRawArrayAttribute(java.lang.String name)

Consumes the named attribute and parses it to an unparsed, unescaped array of Strings. The strings in the attribute may be comma or space separated (or a mix of both).

Returns:

array of String, empty if the attribute was not set.

consumeRawAttribute

public java.lang.String consumeRawAttribute(java.lang.String name)

Consumes the given attribute and returns its trimmed value, or null if it was unset. The returned string is not escaped.

Parameters:

name - the attribute's full name (including prefix)

Returns:

the attribute's value, or ""

consumeRawAttribute

public java.lang.String consumeRawAttribute(java.lang.String name,
                                            java.lang.String defaultValue)

Consumes the given attribute and returns its trimmed value, or the given default value if it was unset. The returned string is not escaped.

Parameters:

name - the attribute's full name (including prefix)

defaultValue - the value to return if the attribute was unset

Returns:

the attribute's value, or defaultValue

consumeRequiredAttribute

public java.lang.String consumeRequiredAttribute(java.lang.String name,
                                                 JType... types)
                                          throws UnableToCompleteException

Consumes the given required attribute as a literal or field reference. The types parameters are required to determine how the value is parsed and validated.

Parameters:

name - the attribute's full name (including prefix)

types - the type(s) this attribute is expected to provide

Returns:

the attribute's value as a Java expression

Throws:

UnableToCompleteException - on parse failure, or if the attribute is empty or unspecified

consumeRequiredDoubleAttribute

public java.lang.String consumeRequiredDoubleAttribute(java.lang.String name)
                                                throws UnableToCompleteException

Convenience method for parsing the named required attribute as a double value or reference.

Returns:

a double literal, an expression that will evaluate to a double value in the generated code

Throws:

UnableToCompleteException - on unparseable value, or if the attribute is empty or unspecified

consumeRequiredRawAttribute

public java.lang.String consumeRequiredRawAttribute(java.lang.String name)
                                             throws UnableToCompleteException

Consumes the named attribute, or dies if it is missing.

Throws:

UnableToCompleteException

consumeSingleChildElement

public XMLElement consumeSingleChildElement()
                                     throws UnableToCompleteException

Consumes a single child element, ignoring any text nodes and throwing an exception if no child is found, or more than one child element is found.

Throws:

UnableToCompleteException - on no children, or too many

consumeStringArrayAttribute

public java.lang.String[] consumeStringArrayAttribute(java.lang.String name)
                                               throws UnableToCompleteException

Consumes the named attribute and parses it to an array of String expressions. The strings in the attribute may be comma or space separated (or a mix of both).

Returns:

array of String expressions, empty if the attribute was not set.

Throws:

UnableToCompleteException - on unparseable value

consumeStringAttribute

public java.lang.String consumeStringAttribute(java.lang.String name)
                                        throws UnableToCompleteException

Convenience method for parsing the named attribute as a String value or reference.

Returns:

an expression that will evaluate to a String value in the generated code, or null if there is no such attribute

Throws:

UnableToCompleteException - on unparseable value

consumeStringAttribute

public java.lang.String consumeStringAttribute(java.lang.String name,
                                               java.lang.String defaultValue)
                                        throws UnableToCompleteException

Convenience method for parsing the named attribute as a String value or reference.

Returns:

an expression that will evaluate to a String value in the generated code, or the given defaultValue if there is no such attribute

Throws:

UnableToCompleteException - on unparseable value

consumeUnescapedInnerText

public java.lang.String consumeUnescapedInnerText()
                                           throws UnableToCompleteException

Returns the unprocessed, unescaped, raw inner text of the receiver. Dies if the receiver has non-text children.

You probably want to use consumeInnerTextEscapedAsHtmlStringLiteral(com.google.gwt.uibinder.rebind.XMLElement.Interpreter) instead.

Returns:

the text

Throws:

UnableToCompleteException - if it held anything other than text nodes

getAttribute

public XMLAttribute getAttribute(int i)

Get the attribute at the given index. If you are consuming attributes, remember to traverse them in reverse.

getAttribute

public XMLAttribute getAttribute(java.lang.String name)

Get the attribute with the given name.

Returns:

the attribute, or null if there is none of that name

getAttributeCount

public int getAttributeCount()

Returns:

The number of attributes this element has

getClosingTag

public java.lang.String getClosingTag()

getLocalName

public java.lang.String getLocalName()

Gets this element's local name (sans namespace prefix).

getLocation

public XMLElement.Location getLocation()

getNamespaceUri

public java.lang.String getNamespaceUri()

Gets this element's namespace URI.

getNamespaceUriForAttribute

public java.lang.String getNamespaceUriForAttribute(java.lang.String fieldName)

getParent

public XMLElement getParent()

Returns:

the parent element, or null if parent is null or a node type other than Element

getPrefix

public java.lang.String getPrefix()

hasAttribute

public boolean hasAttribute(java.lang.String name)

Determines whether the element has a given attribute.

hasChildNodes

public boolean hasChildNodes()

lookupPrefix

public java.lang.String lookupPrefix(java.lang.String prefix)

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.String value)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object