/*
* Copyright 2000-2014 Vaadin Ltd.
*
* 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.vaadin.client;
import java.util.HashSet;
import java.util.Iterator;
import java.util.Set;
import com.google.gwt.core.client.JavaScriptObject;
import com.google.gwt.core.client.JsArrayString;
import com.vaadin.server.PaintTarget;
import com.vaadin.ui.AbstractComponent;
import com.vaadin.ui.Component;
/**
* When a component is updated, it's client side widget's
* {@link ComponentConnector#updateFromUIDL(UIDL, ApplicationConnection)
* updateFromUIDL()} will be called with the updated ("changes") UIDL received
* from the server.
* <p>
* UIDL is hierarchical, and there are a few methods to retrieve the children,
* {@link #getChildCount()}, {@link #getChildIterator()}
* {@link #getChildString(int)}, {@link #getChildUIDL(int)}.
* </p>
* <p>
* It can be helpful to keep in mind that UIDL was originally modeled in XML, so
* it's structure is very XML -like. For instance, the first to children in the
* underlying UIDL representation will contain the "tag" name and attributes,
* but will be skipped by the methods mentioned above.
* </p>
*/
public final class UIDL extends JavaScriptObject {
protected UIDL() {
}
/**
* Shorthand for getting the attribute named "id", which for Paintables is
* the essential paintableId which binds the server side component to the
* client side widget.
*
* @return the value of the id attribute, if available
*/
public String getId() {
return getStringAttribute("id");
}
/**
* Gets the name of this UIDL section, as created with
* {@link PaintTarget#startTag(String) PaintTarget.startTag()} in the
* server-side {@link Component#paint(PaintTarget) Component.paint()} or
* (usually) {@link AbstractComponent#paintContent(PaintTarget)
* AbstractComponent.paintContent()}. Note that if the UIDL corresponds to a
* Paintable, a component identifier will be returned instead - this is used
* internally and is not needed within
* {@link ComponentConnector#updateFromUIDL(UIDL, ApplicationConnection)
* updateFromUIDL()}.
*
* @return the name for this section
*/
public native String getTag()
/*-{
return this[0];
}-*/;
private native ValueMap attr()
/*-{
return this[1];
}-*/;
private native ValueMap var()
/*-{
return this[1]["v"];
}-*/;
private native boolean hasVariables()
/*-{
return Boolean(this[1]["v"]);
}-*/;
/**
* Gets the named attribute as a String.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public String getStringAttribute(String name) {
return attr().getString(name);
}
/**
* Gets the names of the attributes available.
*
* @return the names of available attributes
*/
public Set<String> getAttributeNames() {
Set<String> keySet = attr().getKeySet();
keySet.remove("v");
return keySet;
}
/**
* Gets the names of variables available.
*
* @return the names of available variables
*/
public Set<String> getVariableNames() {
if (!hasVariables()) {
return new HashSet<String>();
} else {
Set<String> keySet = var().getKeySet();
return keySet;
}
}
/**
* Gets the named attribute as an int.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public int getIntAttribute(String name) {
return attr().getInt(name);
}
/**
* Gets the named attribute as a long.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public long getLongAttribute(String name) {
return (long) attr().getRawNumber(name);
}
/**
* Gets the named attribute as a float.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public float getFloatAttribute(String name) {
return (float) attr().getRawNumber(name);
}
/**
* Gets the named attribute as a double.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public double getDoubleAttribute(String name) {
return attr().getRawNumber(name);
}
/**
* Gets the named attribute as a boolean.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public boolean getBooleanAttribute(String name) {
return attr().getBoolean(name);
}
/**
* Gets the named attribute as a Map of named values (key/value pairs).
*
* @param name
* the name of the attribute to get
* @return the attribute Map
*/
public ValueMap getMapAttribute(String name) {
return attr().getValueMap(name);
}
/**
* Gets the named attribute as an array of Strings.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public String[] getStringArrayAttribute(String name) {
return attr().getStringArray(name);
}
/**
* Gets the named attribute as an int array.
*
* @param name
* the name of the attribute to get
* @return the attribute value
*/
public int[] getIntArrayAttribute(final String name) {
return attr().getIntArray(name);
}
/**
* Get attributes value as string whatever the type is
*
* @param name
* @return string presentation of attribute
*/
native String getAttribute(String name)
/*-{
return '' + this[1][name];
}-*/;
native String getVariable(String name)
/*-{
return '' + this[1]['v'][name];
}-*/;
/**
* Indicates whether or not the named attribute is available.
*
* @param name
* the name of the attribute to check
* @return true if the attribute is available, false otherwise
*/
public boolean hasAttribute(final String name) {
return attr().containsKey(name);
}
/**
* Gets the UIDL for the child at the given index.
*
* @param i
* the index of the child to get
* @return the UIDL of the child if it exists
*/
public native UIDL getChildUIDL(int i)
/*-{
return this[i + 2];
}-*/;
/**
* Gets the child at the given index as a String.
*
* @param i
* the index of the child to get
* @return the String representation of the child if it exists
*/
public native String getChildString(int i)
/*-{
return this[i + 2];
}-*/;
private native XML getChildXML(int index)
/*-{
return this[index + 2];
}-*/;
/**
* Gets an iterator that can be used to iterate trough the children of this
* UIDL.
* <p>
* The Object returned by <code>next()</code> will be appropriately typed -
* if it's UIDL, {@link #getTag()} can be used to check which section is in
* question.
* </p>
* <p>
* The basic use case is to iterate over the children of an UIDL update, and
* update the appropriate part of the widget for each child encountered, e.g
* if <code>getTag()</code> returns "color", one would update the widgets
* color to reflect the value of the "color" section.
* </p>
*
* @return an iterator for iterating over UIDL children
*/
public Iterator<Object> getChildIterator() {
return new Iterator<Object>() {
int index = -1;
@Override
public void remove() {
throw new UnsupportedOperationException();
}
@Override
public Object next() {
if (hasNext()) {
int typeOfChild = typeOfChild(++index);
switch (typeOfChild) {
case CHILD_TYPE_UIDL:
UIDL childUIDL = getChildUIDL(index);
return childUIDL;
case CHILD_TYPE_STRING:
return getChildString(index);
case CHILD_TYPE_XML:
return getChildXML(index);
default:
throw new IllegalStateException(
"Illegal child in tag " + getTag()
+ " at index " + index);
}
}
return null;
}
@Override
public boolean hasNext() {
int count = getChildCount();
return count > index + 1;
}
};
}
private static final int CHILD_TYPE_STRING = 0;
private static final int CHILD_TYPE_UIDL = 1;
private static final int CHILD_TYPE_XML = 2;
private native int typeOfChild(int index)
/*-{
var t = typeof this[index + 2];
if(t == "object") {
if(typeof(t.length) == "number") {
return 1;
} else {
return 2;
}
} else if (t == "string") {
return 0;
}
return -1;
}-*/;
/**
* @deprecated
*/
@Deprecated
public String getChildrenAsXML() {
return toString();
}
/**
* Checks if the named variable is available.
*
* @param name
* the name of the variable desired
* @return true if the variable exists, false otherwise
*/
public boolean hasVariable(String name) {
return hasVariables() && var().containsKey(name);
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public String getStringVariable(String name) {
return var().getString(name);
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public int getIntVariable(String name) {
return var().getInt(name);
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public long getLongVariable(String name) {
return (long) var().getRawNumber(name);
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public float getFloatVariable(String name) {
return (float) var().getRawNumber(name);
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public double getDoubleVariable(String name) {
return var().getRawNumber(name);
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public boolean getBooleanVariable(String name) {
return var().getBoolean(name);
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public String[] getStringArrayVariable(String name) {
return var().getStringArray(name);
}
/**
* Gets the value of the named String[] variable as a Set of Strings.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public Set<String> getStringArrayVariableAsSet(final String name) {
final HashSet<String> s = new HashSet<String>();
JsArrayString a = var().getJSStringArray(name);
for (int i = 0; i < a.length(); i++) {
s.add(a.get(i));
}
return s;
}
/**
* Gets the value of the named variable.
*
* @param name
* the name of the variable
* @return the value of the variable
*/
public int[] getIntArrayVariable(String name) {
return var().getIntArray(name);
}
/**
* @deprecated should not be used anymore
*/
@Deprecated
public final static class XML extends JavaScriptObject {
protected XML() {
}
public native String getXMLAsString()
/*-{
var buf = new Array();
var self = this;
for(j in self) {
buf.push("<");
buf.push(j);
buf.push(">");
buf.push(self[j]);
buf.push("</");
buf.push(j);
buf.push(">");
}
return buf.join("");
}-*/;
}
/**
* Returns the number of children.
*
* @return the number of children
*/
public native int getChildCount()
/*-{
return this.length - 2;
}-*/;
native boolean isMapAttribute(String name)
/*-{
return typeof this[1][name] == "object";
}-*/;
/**
* Gets the Paintable with the id found in the named attributes's value.
*
* @param name
* the name of the attribute
* @return the Paintable referenced by the attribute, if it exists
*/
public ServerConnector getPaintableAttribute(String name,
ApplicationConnection connection) {
return ConnectorMap.get(connection).getConnector(
getStringAttribute(name));
}
/**
* Gets the Paintable with the id found in the named variable's value.
*
* @param name
* the name of the variable
* @return the Paintable referenced by the variable, if it exists
*/
public ServerConnector getPaintableVariable(String name,
ApplicationConnection connection) {
return ConnectorMap.get(connection).getConnector(
getStringVariable(name));
}
/**
* Returns the child UIDL by its name. If several child nodes exist with the
* given name, the first child UIDL will be returned.
*
* @param tagName
* @return the child UIDL or null if child wit given name was not found
*/
public UIDL getChildByTagName(String tagName) {
Iterator<Object> childIterator = getChildIterator();
while (childIterator.hasNext()) {
Object next = childIterator.next();
if (next instanceof UIDL) {
UIDL childUIDL = (UIDL) next;
if (childUIDL.getTag().equals(tagName)) {
return childUIDL;
}
}
}
return null;
}
}