com.google.gwt.uibinder.rebind
Class XMLElement

java.lang.Object
  extended by 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
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.
 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.
 com.google.gwt.uibinder.rebind.XMLAttribute getAttribute(int i)
          Get the attribute at the given index.
 com.google.gwt.uibinder.rebind.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".
 Element getElement()
           
 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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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) instead.

Returns:
the text
Throws:
com.google.gwt.core.ext.UnableToCompleteException - if it held anything other than text nodes

getAttribute

public com.google.gwt.uibinder.rebind.XMLAttribute getAttribute(int i)
Get the attribute at the given index. If you are consuming attributes, remember to traverse them in reverse.


getAttribute

public com.google.gwt.uibinder.rebind.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

getElement

public Element getElement()


Copyright © 2012. All Rights Reserved.