diff options
Diffstat (limited to 'server/src/com/vaadin/ui/declarative')
5 files changed, 85 insertions, 88 deletions
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 |