com.google.gwt.uibinder.rebind

Class XMLElement

java.lang.Object

com.google.gwt.uibinder.rebind.XMLElement

public class XMLElement
extends 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

Nested Classes

Modifier and Type	Class and Description
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

Methods

Modifier and Type	Method and Description
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.
String	consumeAttribute(String name, com.google.gwt.core.ext.typeinfo.JType type) Consumes the given attribute as a literal or field reference.
String	consumeAttributeWithDefault(String name, String defaultValue, com.google.gwt.core.ext.typeinfo.JType... types) Like consumeAttributeWithDefault(String, String, JType), but accommodates more complex type signatures.
String	consumeAttributeWithDefault(String name, String defaultValue, com.google.gwt.core.ext.typeinfo.JType type) Consumes the given attribute as a literal or field reference.
String	consumeBooleanAttribute(String name) Convenience method for parsing the named attribute as a boolean value or reference.
String	consumeBooleanAttribute(String name, boolean defaultValue) Convenience method for parsing the named attribute as a boolean value or reference.
Boolean	consumeBooleanConstantAttribute(String name) Consumes the named attribute as a boolean expression.
Iterable<XMLElement>	consumeChildElements() Consumes and returns all child elements.
Collection<XMLElement>	consumeChildElements(XMLElement.Interpreter<Boolean> interpreter) Consumes and returns all child elements selected by the interpreter.
String	consumeImageResourceAttribute(String name) Convenience method for parsing the named attribute as an ImageResource value or reference.
String	consumeInnerHtml(XMLElement.Interpreter<String> interpreter) Consumes all child elements, and returns an HTML interpretation of them.
String	consumeInnerHtml(XMLElement.PostProcessingInterpreter<String> interpreter) Refines consumeInnerHtml(Interpreter) to handle PostProcessingInterpreter.
String	consumeInnerText(XMLElement.PostProcessingInterpreter<String> interpreter) Refines consumeInnerTextEscapedAsHtmlStringLiteral(Interpreter) to handle PostProcessingInterpreter.
String	consumeInnerTextEscapedAsHtmlStringLiteral(XMLElement.Interpreter<String> interpreter) Consumes all child text nodes, and asserts that this element held only text.
String	consumeInnerTextEscapedAsStringLiteral(XMLElement.Interpreter<String> interpreter) Consumes all child text nodes, and asserts that this element held only text.
String	consumeLengthAttribute(String name) Convenience method for parsing the named attribute as a CSS length value.
String	consumeOpeningTag() Consumes all attributes, and returns a string representing the entire opening tag.
String[]	consumeRawArrayAttribute(String name) Consumes the named attribute and parses it to an unparsed, unescaped array of Strings.
String	consumeRawAttribute(String name) Consumes the given attribute and returns its trimmed value, or null if it was unset.
String	consumeRawAttribute(String name, String defaultValue) Consumes the given attribute and returns its trimmed value, or the given default value if it was unset.
String	consumeRequiredAttribute(String name, com.google.gwt.core.ext.typeinfo.JType... types) Consumes the given required attribute as a literal or field reference.
String	consumeRequiredDoubleAttribute(String name) Convenience method for parsing the named required attribute as a double value or reference.
String	consumeRequiredIntAttribute(String name) Convenience method for parsing the named required attribute as a integer value or reference.
String	consumeRequiredRawAttribute(String name) Consumes the named attribute, or dies if it is missing.
String	consumeSafeHtmlAttribute(String name) Convenience method for parsing the named attribute as a SafeHtml value or reference.
String	consumeSafeUriOrStringAttribute(String name) Consumes an attribute as either a SafeUri or a String.
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.
String[]	consumeStringArrayAttribute(String name) Consumes the named attribute and parses it to an array of String expressions.
String	consumeStringAttribute(String name) Convenience method for parsing the named attribute as a String value or reference.
String	consumeStringAttribute(String name, String defaultValue) Convenience method for parsing the named attribute as a String value or reference.
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(String name) Get the attribute with the given name.
int	getAttributeCount() Returns the number of attributes this element has.
String	getClosingTag()
String	getDesignTimePath() Returns the design time path of this element, in form of indexes from root, such as "0/0/1/0".
String	getLocalName() Gets this element's local name (sans namespace prefix).
XMLElement.Location	getLocation()
String	getNamespaceUri() Gets this element's namespace URI.
XMLElement	getParent() Returns the parent element, or null if parent is null or a node type other than Element.
String	getPrefix()
boolean	hasAttribute(String name) Determines whether the element has a given attribute.
boolean	hasChildNodes()
String	lookupPrefix(String prefix)
void	setAttribute(String name, String value)
String	toString()

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode

Method Detail

assertNoAttributes

public void assertNoAttributes()
                        throws com.google.gwt.core.ext.UnableToCompleteException

Ensure that the receiver has no attributes left.

Throws:

com.google.gwt.core.ext.UnableToCompleteException - if it does

assertNoBody

public void assertNoBody()
                  throws com.google.gwt.core.ext.UnableToCompleteException

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException - if it isn't

assertNoText

public void assertNoText()
                  throws com.google.gwt.core.ext.UnableToCompleteException

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException - if it isn't

consumeAttribute

public String consumeAttribute(String name,
                      com.google.gwt.core.ext.typeinfo.JType type)
                        throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on parse failure

consumeAttributeWithDefault

public String consumeAttributeWithDefault(String name,
                                 String defaultValue,
                                 com.google.gwt.core.ext.typeinfo.JType type)
                                   throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on parse failure

consumeAttributeWithDefault

public String consumeAttributeWithDefault(String name,
                                 String defaultValue,
                                 com.google.gwt.core.ext.typeinfo.JType... types)
                                   throws com.google.gwt.core.ext.UnableToCompleteException

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException

consumeBooleanAttribute

public String consumeBooleanAttribute(String name)
                               throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeBooleanAttribute

public String consumeBooleanAttribute(String name,
                             boolean defaultValue)
                               throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeBooleanConstantAttribute

public Boolean consumeBooleanConstantAttribute(String name)
                                        throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeChildElements

public Iterable<XMLElement> consumeChildElements()
                                          throws com.google.gwt.core.ext.UnableToCompleteException

Consumes and returns all child elements.

Throws:

com.google.gwt.core.ext.UnableToCompleteException - if extra text nodes are found

consumeChildElements

public Collection<XMLElement> consumeChildElements(XMLElement.Interpreter<Boolean> interpreter)
                                            throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException

consumeImageResourceAttribute

public String consumeImageResourceAttribute(String name)
                                     throws com.google.gwt.core.ext.UnableToCompleteException

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

Returns:

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeInnerHtml

public String consumeInnerHtml(XMLElement.Interpreter<String> interpreter)
                        throws com.google.gwt.core.ext.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 HtmlInterpreter for an HTML value, or 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:

com.google.gwt.core.ext.UnableToCompleteException

consumeInnerHtml

public String consumeInnerHtml(XMLElement.PostProcessingInterpreter<String> interpreter)
                        throws com.google.gwt.core.ext.UnableToCompleteException

Refines consumeInnerHtml(Interpreter) to handle PostProcessingInterpreter.

Throws:

com.google.gwt.core.ext.UnableToCompleteException

consumeInnerText

public String consumeInnerText(XMLElement.PostProcessingInterpreter<String> interpreter)
                        throws com.google.gwt.core.ext.UnableToCompleteException

Refines consumeInnerTextEscapedAsHtmlStringLiteral(Interpreter) to handle PostProcessingInterpreter.

Throws:

com.google.gwt.core.ext.UnableToCompleteException

consumeInnerTextEscapedAsHtmlStringLiteral

public String consumeInnerTextEscapedAsHtmlStringLiteral(XMLElement.Interpreter<String> interpreter)
                                                  throws com.google.gwt.core.ext.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

This call requires an interpreter to make sense of any special children. The odds are you want to use TextInterpreter

Throws:

com.google.gwt.core.ext.UnableToCompleteException - If any elements present are not consumed by the interpreter

consumeInnerTextEscapedAsStringLiteral

public String consumeInnerTextEscapedAsStringLiteral(XMLElement.Interpreter<String> interpreter)
                                              throws com.google.gwt.core.ext.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 NOT escaped

This call requires an interpreter to make sense of any special children. The odds are you want to use TextInterpreter

Throws:

com.google.gwt.core.ext.UnableToCompleteException - If any elements present are not consumed by the interpreter

consumeLengthAttribute

public String consumeLengthAttribute(String name)
                              throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeOpeningTag

public String consumeOpeningTag()

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

"

consumeRawArrayAttribute

public String[] consumeRawArrayAttribute(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 String consumeRawAttribute(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 String consumeRawAttribute(String name,
                         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 String consumeRequiredAttribute(String name,
                              com.google.gwt.core.ext.typeinfo.JType... types)
                                throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on parse failure, or if the attribute is empty or unspecified

consumeRequiredDoubleAttribute

public String consumeRequiredDoubleAttribute(String name)
                                      throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value, or if the attribute is empty or unspecified

consumeRequiredIntAttribute

public String consumeRequiredIntAttribute(String name)
                                   throws com.google.gwt.core.ext.UnableToCompleteException

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

Returns:

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value, or if the attribute is empty or unspecified

consumeRequiredRawAttribute

public String consumeRequiredRawAttribute(String name)
                                   throws com.google.gwt.core.ext.UnableToCompleteException

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException

consumeSafeHtmlAttribute

public String consumeSafeHtmlAttribute(String name)
                                throws com.google.gwt.core.ext.UnableToCompleteException

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

Returns:

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeSafeUriOrStringAttribute

public String consumeSafeUriOrStringAttribute(String name)
                                       throws com.google.gwt.core.ext.UnableToCompleteException

Consumes an attribute as either a SafeUri or a String. Used in HTML contexts.

Returns:

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

Throws:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeSingleChildElement

public XMLElement consumeSingleChildElement()
                                     throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on no children, or too many

consumeStringArrayAttribute

public String[] consumeStringArrayAttribute(String name)
                                     throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeStringAttribute

public String consumeStringAttribute(String name)
                              throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeStringAttribute

public String consumeStringAttribute(String name,
                            String defaultValue)
                              throws com.google.gwt.core.ext.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:

com.google.gwt.core.ext.UnableToCompleteException - on unparseable value

consumeUnescapedInnerText

public String consumeUnescapedInnerText()
                                 throws com.google.gwt.core.ext.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<java.lang.String>) instead.

Returns:

the text

Throws:

com.google.gwt.core.ext.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(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 String getClosingTag()

getDesignTimePath

public String getDesignTimePath()

Returns the design time path of this element, in form of indexes from root, such as "0/0/1/0".

getLocalName

public String getLocalName()

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

getLocation

public XMLElement.Location getLocation()

getNamespaceUri

public String getNamespaceUri()

Gets this element's namespace URI.

getParent

public XMLElement getParent()

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

getPrefix

public String getPrefix()

hasAttribute

public boolean hasAttribute(String name)

Determines whether the element has a given attribute.

hasChildNodes

public boolean hasChildNodes()

lookupPrefix

public String lookupPrefix(String prefix)

setAttribute

public void setAttribute(String name,
                String value)

toString

public String toString()

Overrides:

toString in class Object