| /* | |
| * Copyright 2011 Google Inc. | |
| * | |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not | |
| * use this file except in compliance with the License. You may obtain a copy of | |
| * the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |
| * License for the specific language governing permissions and limitations under | |
| * the License. | |
| */ | |
| package com.google.gwt.dom.builder.shared; | |
| import com.google.gwt.core.shared.GWT; | |
| import com.google.gwt.dom.client.Element; | |
| import com.google.gwt.regexp.shared.RegExp; | |
| import com.google.gwt.safehtml.shared.SafeHtml; | |
| /** | |
| * Base implementation of {@link ElementBuilderBase} that handles state, but | |
| * nothing else. | |
| * | |
| * <p> | |
| * DO NOT USE THIS CLASS. This class is an implementation class and may change | |
| * in the future. | |
| * </p> | |
| * | |
| * This class is used to ensure that the HTML and DOM implementations throw the | |
| * same exceptions, even if something is valid in one and not the other. For | |
| * example, the DOM implementation supports changing an attribute after setting | |
| * inner HTML, but the HTML version does not, so they should both throw an | |
| * error. Otherwise, they would not be swappable. | |
| */ | |
| public abstract class ElementBuilderImpl { | |
| /** | |
| * A node in the builder stack. | |
| */ | |
| private static class StackNode { | |
| private final ElementBuilderBase<?> builder; | |
| private StackNode next; | |
| private final String tagName; | |
| public StackNode(String tagName, ElementBuilderBase<?> builder) { | |
| this.builder = builder; | |
| this.tagName = tagName; | |
| } | |
| } | |
| /** | |
| * A stack that allows quick access to its top element. | |
| * | |
| * <p> | |
| * FastPeekStack is implemented using a simple linked list of nodes to avoid | |
| * the dynamic casts associated with the emulated version of | |
| * {@link java.util.ArrayList}. When constructing a large DOM structure, such | |
| * as a table, the dynamic casts in ArrayList can significantly degrade | |
| * performance. | |
| * </p> | |
| */ | |
| private class FastPeekStack { | |
| private static final String EMPTY_STACK_MESSAGE = "There are no elements on the stack."; | |
| /** | |
| * The top item in the stack. | |
| */ | |
| private StackNode top; | |
| private int size = 0; | |
| public boolean isEmpty() { | |
| return (top == null); | |
| } | |
| public StackNode peek() { | |
| assertNotEmpty(); | |
| return top; | |
| } | |
| /** | |
| * Pop the current {@link StackNode} and return it. | |
| * | |
| * <p> | |
| * The popped node will be recycled and should not be saved. | |
| * </p> | |
| * | |
| * @return the popped node | |
| */ | |
| public StackNode pop() { | |
| assertNotEmpty(); | |
| StackNode toRet = top; | |
| top = top.next; | |
| size--; | |
| return toRet; | |
| } | |
| public void push(ElementBuilderBase<?> builder, String tagName) { | |
| StackNode node = new StackNode(tagName, builder); | |
| node.next = top; | |
| top = node; | |
| size++; | |
| } | |
| public int size() { | |
| return size; | |
| } | |
| /** | |
| * Assert that the stack is not empty. | |
| * | |
| * @throws IllegalStateException if empty | |
| */ | |
| private void assertNotEmpty() { | |
| if (isEmpty()) { | |
| throw new IllegalStateException(EMPTY_STACK_MESSAGE); | |
| } | |
| } | |
| } | |
| /** | |
| * A regex for matching valid HTML tags. | |
| */ | |
| private static RegExp HTML_TAG_REGEX; | |
| private boolean asElementCalled; | |
| /** | |
| * True if the top most element has not yet been added. | |
| */ | |
| private boolean isEmpty = true; | |
| /** | |
| * True if HTML of text has been added. | |
| */ | |
| private boolean isHtmlOrTextAdded; | |
| /** | |
| * True if the start tag is still open (open bracket '<' but no close | |
| * bracket '>'). | |
| */ | |
| private boolean isStartTagOpen; | |
| /** | |
| * True if the style attribute has been opened and closed. | |
| */ | |
| private boolean isStyleClosed; | |
| /** | |
| * True if the style attribute is open. | |
| */ | |
| private boolean isStyleOpen; | |
| /** | |
| * The stack of element builders. | |
| */ | |
| private final FastPeekStack stack = new FastPeekStack(); | |
| public ElementBuilderImpl() { | |
| if (HTML_TAG_REGEX == null) { | |
| // Starts with a-z, plus 0 or more alphanumeric values (case insensitive). | |
| HTML_TAG_REGEX = RegExp.compile("^[a-z][a-z0-9]*$", "i"); | |
| } | |
| } | |
| public void end() { | |
| endImpl(getCurrentTagName()); | |
| } | |
| public void end(String tagName) { | |
| // Verify the tag name matches the expected tag. | |
| String topItem = getCurrentTagName(); | |
| if (!topItem.equalsIgnoreCase(tagName)) { | |
| throw new IllegalStateException("Specified tag \"" + tagName | |
| + "\" does not match the current element \"" + topItem + "\""); | |
| } | |
| // End the element. | |
| endImpl(topItem); | |
| } | |
| public void endStyle() { | |
| if (!isStyleOpen) { | |
| throw new IllegalStateException( | |
| "Attempting to close a style attribute, but the style attribute isn't open"); | |
| } | |
| maybeCloseStyleAttribute(); | |
| } | |
| /** | |
| * Return the built DOM as an {@link Element}. | |
| * | |
| * @return the {@link Element} that was built | |
| */ | |
| public Element finish() { | |
| if (!GWT.isClient()) { | |
| throw new RuntimeException("asElement() can only be called from GWT client code."); | |
| } | |
| if (asElementCalled) { | |
| throw new IllegalStateException("asElement() can only be called once."); | |
| } | |
| asElementCalled = true; | |
| // End all open tags. | |
| endAllTags(); | |
| return doFinishImpl(); | |
| } | |
| public int getDepth() { | |
| return stack.size(); | |
| } | |
| public void html(SafeHtml html) { | |
| assertStartTagOpen("html cannot be set on an element that already " | |
| + "contains other content or elements."); | |
| lockCurrentElement(); | |
| doHtmlImpl(html); | |
| } | |
| public void onStart(String tagName, ElementBuilderBase<?> builder) { | |
| if (isEmpty) { | |
| isEmpty = false; | |
| } else if (stack.isEmpty()) { | |
| // Check that we aren't creating another top level element. | |
| throw new IllegalStateException("You can only build one top level element."); | |
| } else { | |
| // Check that the element supports children. | |
| assertEndTagNotForbidden("child elements"); | |
| if (!getCurrentBuilder().isChildElementSupported()) { | |
| throw new UnsupportedOperationException(getCurrentTagName() | |
| + " does not support child elements."); | |
| } | |
| } | |
| // Check that asElement hasn't already been called. | |
| if (isHtmlOrTextAdded) { | |
| throw new IllegalStateException("Cannot append an element after setting text of html."); | |
| } | |
| // Validate the tagName. | |
| assertValidTagName(tagName); | |
| maybeCloseStartTag(); | |
| stack.push(builder, tagName); | |
| isStartTagOpen = true; | |
| isStyleOpen = false; | |
| isStyleClosed = false; | |
| isHtmlOrTextAdded = false; | |
| } | |
| /** | |
| * Get the {@link StylesBuilder} used to add style properties to the current | |
| * element. | |
| * | |
| * @return a {@link StylesBuilder} | |
| */ | |
| public abstract StylesBuilder style(); | |
| public void text(String text) { | |
| assertStartTagOpen("text cannot be set on an element that already " | |
| + "contains other content or elements."); | |
| lockCurrentElement(); | |
| doTextImpl(text); | |
| } | |
| /** | |
| * Assert that the builder is in a state where an attribute can be added. | |
| * | |
| * @throw {@link IllegalStateException} if the start tag is closed | |
| */ | |
| protected void assertCanAddAttributeImpl() { | |
| assertStartTagOpen("Attributes cannot be added after appending HTML or adding a child " | |
| + "element."); | |
| maybeCloseStyleAttribute(); | |
| } | |
| /** | |
| * Assert that a style property can be added, and setup the state as if one is | |
| * about to be added. | |
| */ | |
| protected void assertCanAddStylePropertyImpl() { | |
| assertStartTagOpen("Style properties cannot be added after appending HTML or adding a child " | |
| + "element."); | |
| // Check if a style attribute already exists. | |
| if (isStyleClosed) { | |
| throw new IllegalStateException( | |
| "Style properties must be added at the same time. If you already added style properties," | |
| + " you cannot add more after adding non-style attributes."); | |
| } | |
| // Open the style attribute. | |
| if (!isStyleOpen) { | |
| isStyleOpen = true; | |
| doOpenStyleImpl(); | |
| } | |
| } | |
| /** | |
| * Assert that the specified tag name is valid. | |
| * | |
| * @throws IllegalArgumentException if not valid | |
| */ | |
| protected void assertValidTagName(String tagName) { | |
| if (!HTML_TAG_REGEX.test(tagName)) { | |
| throw new IllegalArgumentException("The specified tag name is invalid: " + tagName); | |
| } | |
| } | |
| /** | |
| * Close the start tag. | |
| */ | |
| protected abstract void doCloseStartTagImpl(); | |
| /** | |
| * Close the style attribute. | |
| */ | |
| protected abstract void doCloseStyleAttributeImpl(); | |
| /** | |
| * Self-close the start tag. This method is called for elements that forbid | |
| * the end tag. | |
| */ | |
| protected abstract void doEndStartTagImpl(); | |
| /** | |
| * End the specified tag. | |
| * | |
| * @param tagName the name of the tag to end | |
| */ | |
| protected abstract void doEndTagImpl(String tagName); | |
| /** | |
| * Return the build element. | |
| * | |
| * @return the element | |
| */ | |
| protected abstract Element doFinishImpl(); | |
| /** | |
| * Set the specified html as the inner HTML of the current element. | |
| * | |
| * @param html the HTML to set | |
| */ | |
| protected abstract void doHtmlImpl(SafeHtml html); | |
| /** | |
| * Open the style attribute. | |
| */ | |
| protected abstract void doOpenStyleImpl(); | |
| /** | |
| * Set the specified text as the inner text of the current element. | |
| * | |
| * @param text the text to set | |
| */ | |
| protected abstract void doTextImpl(String text); | |
| /** | |
| * End all open tags, including the root element. | |
| * | |
| * <p> | |
| * Doing so also ensures that all builder methods will throw an exception | |
| * because the stack is empty, and a new element cannot be started. | |
| * </p> | |
| */ | |
| protected void endAllTags() { | |
| while (!stack.isEmpty()) { | |
| end(); | |
| } | |
| } | |
| /** | |
| * Lock the current element, preventing any additional changes to it. The only | |
| * valid option is to call {@link #end()}. | |
| */ | |
| protected void lockCurrentElement() { | |
| maybeCloseStartTag(); | |
| assertEndTagNotForbidden("html"); | |
| isHtmlOrTextAdded = true; | |
| } | |
| /** | |
| * Assert that the current builder does not forbid end tags. | |
| * | |
| * @param operation the operation that the user is attempting | |
| * @throw {@link UnsupportedOperationException} if not supported | |
| */ | |
| private void assertEndTagNotForbidden(String operation) { | |
| if (getCurrentBuilder().isEndTagForbidden()) { | |
| throw new UnsupportedOperationException(getCurrentTagName() + " does not support " | |
| + operation); | |
| } | |
| } | |
| /** | |
| * Assert that the start tag is still open. | |
| * | |
| * @param message the error message if the start tag is not open | |
| * @throw {@link IllegalStateException} if the start tag is closed | |
| */ | |
| private void assertStartTagOpen(String message) { | |
| if (!isStartTagOpen) { | |
| throw new IllegalStateException(message); | |
| } | |
| } | |
| /** | |
| * End the current element without checking the tag name. | |
| * | |
| * @param tagName the tag name to end | |
| */ | |
| private void endImpl(String tagName) { | |
| // Close the start tag. | |
| maybeCloseStartTag(); | |
| /* | |
| * End the tag. The tag name is safe because it comes from the stack, and | |
| * tag names are checked before they are added to the stack. | |
| */ | |
| if (getCurrentBuilder().isEndTagForbidden()) { | |
| doEndStartTagImpl(); | |
| } else { | |
| doEndTagImpl(tagName); | |
| } | |
| // Popup the item off the top of the stack. | |
| isStartTagOpen = false; // Closed because this element was added. | |
| isStyleClosed = true; // Too late to add styles. | |
| stack.pop(); | |
| /* | |
| * If this element was added, then we did not add html or text to the | |
| * parent. | |
| */ | |
| isHtmlOrTextAdded = false; | |
| } | |
| /** | |
| * Get the builder at the top of the stack. | |
| * | |
| * @return an {@link ElementBuilderBase} | |
| * @throws IllegalStateException if there are no elements on the stack | |
| */ | |
| private ElementBuilderBase<?> getCurrentBuilder() { | |
| return stack.peek().builder; | |
| } | |
| /** | |
| * Get the tag name of the element at the top of the stack. | |
| * | |
| * @return a tag name | |
| * @throws IllegalStateException if there are no elements on the stack | |
| */ | |
| private String getCurrentTagName() { | |
| return stack.peek().tagName; | |
| } | |
| /** | |
| * Close the start tag if it is still open. | |
| */ | |
| private void maybeCloseStartTag() { | |
| maybeCloseStyleAttribute(); | |
| if (isStartTagOpen) { | |
| isStartTagOpen = false; | |
| /* | |
| * Close the start tag, unless the end tag is forbidden. If the end tag is | |
| * forbidden, the only valid call is to #end(), which will self end the | |
| * start tag. | |
| */ | |
| if (!getCurrentBuilder().isEndTagForbidden()) { | |
| doCloseStartTagImpl(); | |
| } | |
| } | |
| } | |
| /** | |
| * Close the style attribute if it is still open. | |
| */ | |
| private void maybeCloseStyleAttribute() { | |
| if (isStyleOpen) { | |
| isStyleOpen = false; | |
| isStyleClosed = true; | |
| doCloseStyleAttributeImpl(); | |
| } | |
| } | |
| } |