aboutsummaryrefslogtreecommitdiffstats
path: root/server/src
diff options
context:
space:
mode:
Diffstat (limited to 'server/src')
-rw-r--r--server/src/com/vaadin/ui/AbstractComponent.java18
-rw-r--r--server/src/com/vaadin/ui/AbstractOrderedLayout.java2
-rw-r--r--server/src/com/vaadin/ui/AbstractSingleComponentContainer.java2
-rw-r--r--server/src/com/vaadin/ui/CssLayout.java2
-rw-r--r--server/src/com/vaadin/ui/declarative/Design.java105
-rw-r--r--server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java22
-rw-r--r--server/src/com/vaadin/ui/declarative/DesignContext.java20
-rw-r--r--server/src/com/vaadin/ui/declarative/DesignException.java8
-rw-r--r--server/src/com/vaadin/ui/declarative/FieldBinder.java18
9 files changed, 97 insertions, 100 deletions
diff --git a/server/src/com/vaadin/ui/AbstractComponent.java b/server/src/com/vaadin/ui/AbstractComponent.java
index 5f9ce0edcd..5b7492dbdb 100644
--- a/server/src/com/vaadin/ui/AbstractComponent.java
+++ b/server/src/com/vaadin/ui/AbstractComponent.java
@@ -965,7 +965,7 @@ public abstract class AbstractComponent extends AbstractClientConnector
for (Attribute a : attr) {
if (!a.getKey().startsWith(":") && !supported.contains(a.getKey())) {
getLogger().info(
- "Unsupported attribute found when synchronizing from design : "
+ "Unsupported attribute found when reading from design : "
+ a.getKey());
}
}
@@ -1041,8 +1041,8 @@ public abstract class AbstractComponent extends AbstractClientConnector
}
/**
- * Synchronizes the size of this component from the given design attributes.
- * If the attributes do not contain relevant size information, defaults is
+ * Reads the size of this component from the given design attributes. If the
+ * attributes do not contain relevant size information, defaults is
* consulted.
*
* @param attributes
@@ -1169,12 +1169,12 @@ public abstract class AbstractComponent extends AbstractClientConnector
/**
* Returns a collection of attributes that do not require custom handling
- * when synchronizing from design. These are typically attributes of some
+ * when reading or writing design. These are typically attributes of some
* primitive type. The default implementation searches setters with
* primitive values
*
- * @return a collection of attributes that can be synchronized from design
- * using the default approach.
+ * @return a collection of attributes that can be read and written using the
+ * default approach.
*/
private Collection<String> getDefaultAttributes() {
Collection<String> attributes = DesignAttributeHandler
@@ -1185,9 +1185,9 @@ public abstract class AbstractComponent extends AbstractClientConnector
/**
* Returns a collection of attributes that should not be handled by the
- * basic implementation of the {@link synhronizeFromDesign} and
- * {@link writeDesign} methods. Typically these are handled in a custom way
- * in the overridden versions of the above methods
+ * basic implementation of the {@link readDesign} and {@link writeDesign}
+ * methods. Typically these are handled in a custom way in the overridden
+ * versions of the above methods
*
* @return the collection of attributes that are not handled by the basic
* implementation
diff --git a/server/src/com/vaadin/ui/AbstractOrderedLayout.java b/server/src/com/vaadin/ui/AbstractOrderedLayout.java
index ae8f3198bf..77c7e3c826 100644
--- a/server/src/com/vaadin/ui/AbstractOrderedLayout.java
+++ b/server/src/com/vaadin/ui/AbstractOrderedLayout.java
@@ -530,7 +530,7 @@ public abstract class AbstractOrderedLayout extends AbstractLayout implements
*/
@Override
public void writeDesign(Element design, DesignContext designContext) {
- // synchronize default attributes
+ // write default attributes
super.writeDesign(design, designContext);
// handle margin
AbstractOrderedLayout def = (AbstractOrderedLayout) designContext
diff --git a/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java b/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java
index 034c285670..24c36fd0cf 100644
--- a/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java
+++ b/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java
@@ -310,7 +310,7 @@ public abstract class AbstractSingleComponentContainer extends
*/
@Override
public void writeDesign(Element design, DesignContext designContext) {
- // synchronize default attributes (also clears children and attributes)
+ // write default attributes (also clears children and attributes)
super.writeDesign(design, designContext);
AbstractSingleComponentContainer def = designContext
.getDefaultInstance(this);
diff --git a/server/src/com/vaadin/ui/CssLayout.java b/server/src/com/vaadin/ui/CssLayout.java
index f3ae6c0695..528b34a28f 100644
--- a/server/src/com/vaadin/ui/CssLayout.java
+++ b/server/src/com/vaadin/ui/CssLayout.java
@@ -382,7 +382,7 @@ public class CssLayout extends AbstractLayout implements LayoutClickNotifier {
*/
@Override
public void writeDesign(Element design, DesignContext designContext) {
- // synchronize default attributes
+ // write default attributes
super.writeDesign(design, designContext);
CssLayout def = designContext.getDefaultInstance(this);
// handle children
diff --git a/server/src/com/vaadin/ui/declarative/Design.java b/server/src/com/vaadin/ui/declarative/Design.java
index 138214af6b..ff564fabc3 100644
--- a/server/src/com/vaadin/ui/declarative/Design.java
+++ b/server/src/com/vaadin/ui/declarative/Design.java
@@ -16,7 +16,6 @@
package com.vaadin.ui.declarative;
import java.beans.IntrospectionException;
-import java.io.BufferedWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
@@ -39,10 +38,11 @@ import com.vaadin.ui.declarative.DesignContext.ComponentCreatedEvent;
import com.vaadin.ui.declarative.DesignContext.ComponentCreationListener;
/**
- * Design is used for parsing a component hierarchy from an html file and,
- * conversely, for generating an html tree representation corresponding to a
- * given component hierarchy. For both parsing and tree generation the component
- * hierarchy must contain a single root.
+ * Design is used for reading a component hierarchy from an html string or input
+ * stream and, conversely, for writing an html representation corresponding to a
+ * given component hierarchy. The component hierarchy must contain one root
+ * component. An empty component hierarchy can be represented using null as the
+ * root node.
*
*
* @since 7.4
@@ -51,7 +51,7 @@ import com.vaadin.ui.declarative.DesignContext.ComponentCreationListener;
public class Design implements Serializable {
/**
* Parses the given input stream into a jsoup document
- *
+ *
* @param html
* the stream containing the design
* @return the parsed jsoup document
@@ -69,14 +69,14 @@ public class Design implements Serializable {
/**
* Constructs a component hierarchy from the design specified as an html
- * document. The component hierarchy must contain exactly one top-level
- * Component. The component should be located under <body>, but also invalid
- * html containing the hierarchy without <html>, <head> and <body> tags is
- * accepted. You can optionally pass instance for the root component with
- * some uninitialized instance fields. The fields will be automatically
- * populated when parsing the design based on the component ids, local ids,
- * and captions of the components in the design.
- *
+ * document. The hierarchy must contain at most one top-level component,
+ * which should be located under <body>. Also invalid html containing the
+ * hierarchy without <html>, <head> and <body> tags is accepted. You can
+ * optionally pass instance for the root component with some uninitialized
+ * instance fields. The fields will be automatically populated when parsing
+ * the design based on the component ids, local ids, and captions of the
+ * components in the design.
+ *
* @param html
* the html document describing the component design
* @param rootInstance
@@ -95,14 +95,14 @@ public class Design implements Serializable {
/**
* Constructs a component hierarchy from the design specified as an html
- * document given as a string. The component hierarchy must contain exactly
- * one top-level Component. The component should be located under <body>,
- * but also invalid html containing the hierarchy without <html>, <head> and
- * <body> tags is accepted. You can optionally pass instance for the root
- * component with some uninitialized instance fields. The fields will be
- * automatically populated when parsing the design based on the component
- * ids, local ids, and captions of the components in the design.
- *
+ * document given as a string. The hierarchy must contain at most one
+ * top-level component, which should be located under <body>. Also invalid
+ * html containing the hierarchy without <html>, <head> and <body> tags is
+ * accepted. You can optionally pass instance for the root component with
+ * some uninitialized instance fields. The fields will be automatically
+ * populated when parsing the design based on the component ids, local ids,
+ * and captions of the components in the design.
+ *
* @param html
* the html document describing the component design
* @param rootInstance
@@ -124,9 +124,9 @@ public class Design implements Serializable {
* tree.
*
* If a component root is given, the component instances created during
- * synchronizing the design are assigned to its member fields based on their
- * id, local id, and caption
- *
+ * reading the design are assigned to its member fields based on their id,
+ * local id, and caption
+ *
* @param doc
* the html tree
* @param componentRoot
@@ -151,9 +151,9 @@ public class Design implements Serializable {
* tree.
*
* If a component root is given, the component instances created during
- * synchronizing the design are assigned to its member fields based on their
- * id, local id, and caption
- *
+ * reading the design are assigned to its member fields based on their id,
+ * local id, and caption
+ *
* @param doc
* the html tree
* @param componentRoot
@@ -218,13 +218,14 @@ public class Design implements Serializable {
}
/**
- * Generates an html tree representation representing the component
- * hierarchy having the given root. The hierarchy is stored under <body> in
- * the tree. The generated tree corresponds to a valid html document.
- *
- *
- * @param root
- * the root of the component hierarchy
+ * Generates an html tree representation of the component hierarchy having
+ * the root designContext.getRootComponent(). The hierarchy is stored under
+ * <body> in the tree. The generated tree represents a valid html document.
+ *
+ *
+ * @param designContext
+ * a DesignContext object specifying the root component
+ * (designContext.getRootComponent()) of the hierarchy
* @return an html tree representation of the component hierarchy
*/
private static Document createHtml(DesignContext designContext) {
@@ -249,20 +250,6 @@ public class Design implements Serializable {
}
/**
- * Generates an html file corresponding to the component hierarchy with the
- * given root.
- *
- * @param writer
- * @param root
- * @throws IOException
- */
- private static void createHtml(BufferedWriter writer, DesignContext ctx)
- throws IOException {
- String docAsString = createHtml(ctx).toString();
- writer.write(docAsString);
- }
-
- /**
* Loads a design for the given root component.
* <p>
* This methods assumes that the component class (or a super class) has been
@@ -358,7 +345,7 @@ public class Design implements Serializable {
* design. Matching is done based on field name in the component class and
* id/local id/caption in the design file.
* <p>
- * The type of the root component must match the root element in the design
+ * The type of the root component must match the root element in the design.
*
* @param filename
* The file name to load. Loaded from the same package as the
@@ -382,14 +369,16 @@ public class Design implements Serializable {
}
/**
- * Loads a design from the given stream using the given root component.
+ * Loads a design from the given stream using the given root component. If
+ * rootComponent is null, the type of the root node is read from the design.
* <p>
* Any {@link Component} type fields in the root component which are not
* assigned (i.e. are null) are mapped to corresponding components in the
* design. Matching is done based on field name in the component class and
* id/local id/caption in the design file.
* <p>
- * The type of the root component must match the root element in the design
+ * If rootComponent is not null, its type must match the type of the root
+ * element in the design
*
* @param stream
* The stream to read the design from
@@ -413,13 +402,12 @@ public class Design implements Serializable {
* Loads a design from the given input stream
*
* @param design
- * The input stream which contains the design
+ * The stream to read the design from
* @return The root component of the design
*/
public static Component read(InputStream design) {
DesignContext context = read(design, null);
return context.getRootComponent();
-
}
/**
@@ -427,7 +415,7 @@ public class Design implements Serializable {
* stream
*
* @param component
- * the root component of the component tree to write
+ * the root component of the component tree
* @param outputStream
* the output stream to write the design to. The design is always
* written as UTF-8
@@ -445,8 +433,9 @@ public class Design implements Serializable {
* the given output stream. The design context is used for writing local ids
* and other information not available in the component tree.
*
- * @param component
- * the root component of the component tree to write
+ * @param designContext
+ * the DesignContext object specifying the component hierarchy
+ * and the local id values of the objects
* @param outputStream
* the output stream to write the design to. The design is always
* written as UTF-8
@@ -477,4 +466,4 @@ public class Design implements Serializable {
outputStream.write(doc.html().getBytes());
}
-}
+} \ No newline at end of file
diff --git a/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java b/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java
index 7b0c039e4a..7c106cec44 100644
--- a/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java
+++ b/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java
@@ -232,16 +232,12 @@ public class DesignAttributeHandler implements Serializable {
}
/**
- * Reads the given attribute from attributes. If the attribute is not found,
- * the provided default value is returned
+ * Reads the given attribute from attributes.
*
* @param attribute
* the attribute key
* @param attributes
* the set of attributes to read from
- * @param defaultValue
- * the default value that is returned if the attribute is not
- * found
* @param outputType
* the output type for the attribute
* @return the attribute value or the default value if the attribute is not
@@ -269,7 +265,7 @@ public class DesignAttributeHandler implements Serializable {
/**
* Writes the given attribute value to attributes if it differs from the
- * default attribute value
+ * default attribute value.
*
* @param attribute
* the attribute key
@@ -279,8 +275,8 @@ public class DesignAttributeHandler implements Serializable {
* the attribute value
* @param defaultValue
* the default attribute value
- * @param the
- * type of the input value
+ * @param inputType
+ * the type of the input value
*/
public static <T> void writeAttribute(String attribute,
Attributes attributes, T value, T defaultValue, Class<T> inputType) {
@@ -377,9 +373,8 @@ public class DesignAttributeHandler implements Serializable {
}
/**
- * Creates the decimal format used when writing attributes to the design
+ * Creates the decimal format used when writing attributes to the design.
*
- * @since 7.4
* @return the decimal format
*/
private static DecimalFormat getDecimalFormat() {
@@ -622,7 +617,6 @@ public class DesignAttributeHandler implements Serializable {
* Provides mappings between shortcut keycodes and their representation in
* design attributes
*
- * @since 7.4
* @author Vaadin Ltd
*/
private static class ShortcutKeyMapper implements Serializable {
@@ -721,8 +715,8 @@ public class DesignAttributeHandler implements Serializable {
/**
* Converts the given string attribute value to its corresponding boolean.
*
- * An empty string is considered true (true when attribute exists),
- * otherwise "false" and "true" are supported, all other input will throw an
+ * An empty string and "true" are considered to represent a true value and
+ * "false" to represent a false value. All other input will throw an
* exception
*
* @param booleanValue
@@ -733,4 +727,4 @@ public class DesignAttributeHandler implements Serializable {
return "".equals(booleanValue) ? true : Boolean.valueOf(booleanValue);
}
-}
+} \ No newline at end of file
diff --git a/server/src/com/vaadin/ui/declarative/DesignContext.java b/server/src/com/vaadin/ui/declarative/DesignContext.java
index c5094d7927..25765611aa 100644
--- a/server/src/com/vaadin/ui/declarative/DesignContext.java
+++ b/server/src/com/vaadin/ui/declarative/DesignContext.java
@@ -55,12 +55,12 @@ public class DesignContext implements Serializable {
public static final String ID_ATTRIBUTE = "id";
public static final String CAPTION_ATTRIBUTE = "caption";
public static final String LOCAL_ID_ATTRIBUTE = "_id";
- // Mappings from ids to components. Modified when synchronizing from design.
+ // Mappings from ids to components. Modified when reading from design.
private Map<String, Component> idToComponent = new HashMap<String, Component>();
private Map<String, Component> localIdToComponent = new HashMap<String, Component>();
private Map<String, Component> captionToComponent = new HashMap<String, Component>();
- // Mapping from components to local ids. Accessed when synchronizing to
- // design. Modified when synchronizing from design.
+ // Mapping from components to local ids. Accessed when writing to
+ // design. Modified when reading from design.
private Map<Component, String> componentToLocalId = new HashMap<Component, String>();
private Document doc; // required for calling createElement(String)
// namespace mappings
@@ -329,7 +329,12 @@ public class DesignContext implements Serializable {
}
/**
+ * Stores the package mappings (prefix -> package name) of this object to
+ * the specified document. The prefixes are stored as <meta> tags under
+ * <head> in the document.
*
+ * @param doc
+ * the Jsoup document tree where the package mappings are stored
*/
public void storePrefixes(Document doc) {
Element head = doc.head();
@@ -355,7 +360,7 @@ public class DesignContext implements Serializable {
* returned Node.
*
* @param childComponent
- * The component with state that is synchronized in to the node
+ * The component with state that is written in to the node
* @return An html tree node corresponding to the given component. The tag
* name of the created node is derived from the class name of
* childComponent.
@@ -570,7 +575,7 @@ public class DesignContext implements Serializable {
/**
* Returns the root component of a created component hierarchy.
*
- * @return
+ * @return the root component of the hierarchy
*/
public Component getRootComponent() {
return rootComponent;
@@ -578,6 +583,9 @@ public class DesignContext implements Serializable {
/**
* Sets the root component of a created component hierarchy.
+ *
+ * @param rootComponent
+ * the root component of the hierarchy
*/
public void setRootComponent(Component rootComponent) {
this.rootComponent = rootComponent;
@@ -690,7 +698,7 @@ public class DesignContext implements Serializable {
* The component being written
* @param defaultC
* The default instance for the component
- * @return
+ * @return whether the children of c should be written
*/
public boolean shouldWriteChildren(Component c, Component defaultC) {
if (c == getRootComponent()) {
diff --git a/server/src/com/vaadin/ui/declarative/DesignException.java b/server/src/com/vaadin/ui/declarative/DesignException.java
index 071e280b78..01482f84b0 100644
--- a/server/src/com/vaadin/ui/declarative/DesignException.java
+++ b/server/src/com/vaadin/ui/declarative/DesignException.java
@@ -16,6 +16,12 @@
package com.vaadin.ui.declarative;
@SuppressWarnings("serial")
+/**
+ * An exception that is used when reading or writing a design fails.
+ *
+ * @since 7.4
+ * @author Vaadin Ltd
+ */
public class DesignException extends RuntimeException {
public DesignException() {
@@ -30,4 +36,4 @@ public class DesignException extends RuntimeException {
super(message, e);
}
-}
+} \ No newline at end of file
diff --git a/server/src/com/vaadin/ui/declarative/FieldBinder.java b/server/src/com/vaadin/ui/declarative/FieldBinder.java
index 4826c2be64..af82d9c58c 100644
--- a/server/src/com/vaadin/ui/declarative/FieldBinder.java
+++ b/server/src/com/vaadin/ui/declarative/FieldBinder.java
@@ -45,7 +45,7 @@ public class FieldBinder implements Serializable {
private Map<String, Field> fieldMap = new HashMap<String, Field>();
/**
- * Creates a new instance of LayoutFieldBinder
+ * Creates a new instance of LayoutFieldBinder.
*
* @param design
* the design class instance containing the fields to bind
@@ -57,7 +57,7 @@ public class FieldBinder implements Serializable {
}
/**
- * Creates a new instance of LayoutFieldBinder
+ * Creates a new instance of LayoutFieldBinder.
*
* @param design
* the instance containing the fields
@@ -76,7 +76,7 @@ public class FieldBinder implements Serializable {
}
/**
- * Returns a collection of field names that are not bound
+ * Returns a collection of field names that are not bound.
*
* @return a collection of fields assignable to Component that are not bound
*/
@@ -104,7 +104,7 @@ public class FieldBinder implements Serializable {
}
/**
- * Resolves the fields of the design class instance
+ * Resolves the fields of the design class instance.
*/
private void resolveFields(Class<?> classWithFields) {
for (Field memberField : getFieldsInDeclareOrder(classWithFields)) {
@@ -217,7 +217,7 @@ public class FieldBinder implements Serializable {
/**
* Converts the given identifier to a valid field name by stripping away
- * illegal character and setting the first letter of the name to lowercase
+ * illegal character and setting the first letter of the name to lower case.
*
* @param identifier
* the identifier to be converted to field name
@@ -242,10 +242,10 @@ public class FieldBinder implements Serializable {
}
/**
- * Returns an array containing Field objects reflecting all the fields of
- * the class or interface represented by this Class object. The elements in
- * the array returned are sorted in declare order. The fields in
- * superclasses are excluded.
+ * Returns a list containing Field objects reflecting all the fields of the
+ * class or interface represented by this Class object. The elements in the
+ * returned list are sorted in declare order. The fields in superclasses are
+ * excluded.
*
* @param searchClass
* the class to be scanned for fields