Package com.vaadin.server

Class JsonPaintTarget

java.lang.Object

com.vaadin.server.JsonPaintTarget

All Implemented Interfaces:

PaintTarget, Serializable

public class JsonPaintTarget
extends Object
implements PaintTarget

User Interface Description Language Target. TODO document better: role of this class, UIDL format, attributes, variables, etc.

Since:

5.0

Author:

Vaadin Ltd.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.vaadin.server.PaintTarget

PaintTarget.PaintStatus

Constructor Summary

Constructors

Constructor	Description
JsonPaintTarget(LegacyCommunicationManager manager, Writer outWriter, boolean cachingRequired)	Creates a new JsonPaintTarget.

Method Summary

Modifier and Type	Method	Description
void	addAttribute(String name, boolean value)	Adds a boolean attribute to component.
void	addAttribute(String name, double value)	Adds a double attribute to component.
void	addAttribute(String name, float value)	Adds a float attribute to component.
void	addAttribute(String name, int value)	Adds a integer attribute to component.
void	addAttribute(String name, long value)	Adds a long attribute to component.
void	addAttribute(String name, Resource value)	Adds a resource attribute to component.
void	addAttribute(String name, Component value)	Adds a Component type attribute.
void	addAttribute(String name, Object[] values)
void	addAttribute(String name, String value)	Adds a string attribute to component.
void	addAttribute(String name, Map<?,?> value)	TODO
void	addCharacterData(String text)	Adds CDATA node to target UIDL-tree.
void	addSection(String sectionTagName, String sectionData)	Prints the single text section.
void	addText(String str)	Prints XML-escaped text.
void	addUIDL(String xml)	Adds XML directly to UIDL.
void	addUploadStreamVariable(VariableOwner owner, String name)	Adds a upload stream type variable.
void	addVariable(VariableOwner owner, String name, boolean value)	Adds a boolean type variable.
void	addVariable(VariableOwner owner, String name, double value)	Adds a double type variable.
void	addVariable(VariableOwner owner, String name, float value)	Adds a float type variable.
void	addVariable(VariableOwner owner, String name, int value)	Adds a int type variable.
void	addVariable(VariableOwner owner, String name, long value)	Adds a long type variable.
void	addVariable(VariableOwner owner, String name, StreamVariable value)	Adds details about StreamVariable to the UIDL stream.
void	addVariable(VariableOwner owner, String name, Component value)	Adds a Component type variable.
void	addVariable(VariableOwner owner, String name, String value)	Adds a string type variable.
void	addVariable(VariableOwner owner, String name, String[] value)	Adds a string array type variable.
void	addXMLSection(String sectionTagName, String sectionData, String namespace)	Adds XML section with namespace.
void	close()	Closes the paint target.
void	endPaintable(Component paintable)	Prints paintable element end tag.
void	endTag(String tagName)	Prints the element end tag.
static String	escapeJSON(String s)	Escapes the given string so it can safely be used as a JSON string.
static String	escapeXML(String xml)	Substitutes the XML sensitive characters with predefined XML entities.
String	getTag(ClientConnector clientConnector)
String	getUIDL()	Gets the UIDL already printed to stream.
Collection<Class<? extends ClientConnector>>	getUsedClientConnectors()
Set<Object>	getUsedResources()
boolean	isFullRepaint()
PaintTarget.PaintStatus	startPaintable(Component connector, String tagName)	Prints element start tag of a paintable section.
void	startTag(String tagName)	Prints element start tag.
void	startTag(String tagName, boolean isChildNode)	Prints the element start tag.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JsonPaintTarget

public JsonPaintTarget(LegacyCommunicationManager manager,
                       Writer outWriter,
                       boolean cachingRequired)
                throws PaintException

Creates a new JsonPaintTarget.

Parameters:

manager -

outWriter - A character-output stream.

cachingRequired - true if this is not a full repaint, i.e. caches are to be used.

Throws:

PaintException - if the paint operation failed.

Method Detail

startTag

public void startTag(String tagName)
              throws PaintException

Description copied from interface: PaintTarget

Prints element start tag.

 Todo:
 Checking of input values
 

Specified by:

startTag in interface PaintTarget

Parameters:

tagName - the name of the start tag.

Throws:

PaintException - if the paint operation failed.

startTag

public void startTag(String tagName,
                     boolean isChildNode)
              throws PaintException

Prints the element start tag.

   Todo:
    Checking of input values

 

Parameters:

tagName - the name of the start tag.

Throws:

PaintException - if the paint operation failed.

endTag

public void endTag(String tagName)
            throws PaintException

Prints the element end tag. If the parent tag is closed before every child tag is closed an PaintException is raised.

Specified by:

endTag in interface PaintTarget

Parameters:

tag - the name of the end tag.

Throws:

PaintException - if the paint operation failed.

escapeXML

public static String escapeXML(String xml)

Substitutes the XML sensitive characters with predefined XML entities.

Parameters:

xml - the String to be substituted.

Returns:

A new string instance where all occurrences of XML sensitive characters are substituted with entities.

escapeJSON

public static String escapeJSON(String s)

Escapes the given string so it can safely be used as a JSON string.

Parameters:

s - The string to escape

Returns:

Escaped version of the string

addText

public void addText(String str)
             throws PaintException

Prints XML-escaped text.

Specified by:

addText in interface PaintTarget

Parameters:

str -

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         boolean value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a boolean attribute to component. Atributes must be added before any content is written.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         Resource value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a resource attribute to component. Atributes must be added before any content is written.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the Attribute name

value - the Attribute value

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         int value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a integer attribute to component. Atributes must be added before any content is written.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         long value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a long attribute to component. Atributes must be added before any content is written.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         float value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a float attribute to component. Atributes must be added before any content is written.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         double value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a double attribute to component. Atributes must be added before any content is written.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         String value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a string attribute to component. Atributes must be added before any content is written.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the Boolean attribute name.

value - the Boolean attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

public void addAttribute(String name,
                         Component value)
                  throws PaintException

Description copied from interface: PaintTarget

Adds a Component type attribute. On client side the value will be a terminal specific reference to corresponding component on client side implementation.

Specified by:

addAttribute in interface PaintTarget

Parameters:

name - the name of the attribute

value - the Component to be referenced on client side

Throws:

PaintException

addAttribute

public void addAttribute(String name,
                         Map<?,?> value)
                  throws PaintException

Description copied from interface: PaintTarget

TODO

Specified by:

addAttribute in interface PaintTarget

Throws:

PaintException

addAttribute

public void addAttribute(String name,
                         Object[] values)

Specified by:

addAttribute in interface PaintTarget

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        String value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a string type variable.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        Component value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a Component type variable. On client side the variable value will be a terminal specific reference to corresponding component on client side implementation. When updated from client side, terminal will map the client side component reference back to a corresponding server side reference.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes

name - the name of the variable

value - the initial value of the variable

Throws:

PaintException - if the paint oparation fails

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        int value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a int type variable.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        long value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a long type variable.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        float value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a float type variable.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        double value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a double type variable.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        boolean value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a boolean type variable.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        String[] value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds a string array type variable.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addUploadStreamVariable

public void addUploadStreamVariable(VariableOwner owner,
                                    String name)
                             throws PaintException

Adds a upload stream type variable. TODO not converted for JSON

Specified by:

addUploadStreamVariable in interface PaintTarget

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

Throws:

PaintException - if the paint operation failed.

addSection

public void addSection(String sectionTagName,
                       String sectionData)
                throws PaintException

Prints the single text section. Prints full text section. The section data is escaped

Specified by:

addSection in interface PaintTarget

Parameters:

sectionTagName - the name of the tag.

sectionData - the section data to be printed.

Throws:

PaintException - if the paint operation failed.

addUIDL

public void addUIDL(String xml)
             throws PaintException

Adds XML directly to UIDL.

Specified by:

addUIDL in interface PaintTarget

Parameters:

xml - the Xml to be added.

Throws:

PaintException - if the paint operation failed.

addXMLSection

public void addXMLSection(String sectionTagName,
                          String sectionData,
                          String namespace)
                   throws PaintException

Adds XML section with namespace.

Specified by:

addXMLSection in interface PaintTarget

Parameters:

sectionTagName - the name of the tag.

sectionData - the section data.

namespace - the namespace to be added.

Throws:

PaintException - if the paint operation failed.

See Also:

PaintTarget.addXMLSection(String, String, String)

getUIDL

public String getUIDL()

Gets the UIDL already printed to stream. Paint target must be closed before the getUIDL can be called.

Returns:

the UIDL.

close

public void close()
           throws PaintException

Closes the paint target. Paint target must be closed before the getUIDL can be called. Subsequent attempts to write to paint target. If the target was already closed, call to this function is ignored. will generate an exception.

Throws:

PaintException - if the paint operation failed.

startPaintable

public PaintTarget.PaintStatus startPaintable(Component connector,
                                              String tagName)
                                       throws PaintException

Description copied from interface: PaintTarget

Prints element start tag of a paintable section. Starts a paintable section using the given tag. The PaintTarget may implement a caching scheme, that checks the paintable has actually changed or can a cached version be used instead. This method should call the startTag method.

If the Component is found in cache and this function returns true it may omit the content and close the tag, in which case cached content should be used.

This method may also add only a reference to the paintable and queue the paintable to be painted separately.

Each paintable being painted should be closed by a matching PaintTarget.endPaintable(Component) regardless of the PaintTarget.PaintStatus returned.

Specified by:

startPaintable in interface PaintTarget

Parameters:

connector - the paintable to start.

tagName - the name of the start tag.

Returns:

PaintTarget.PaintStatus - ready to paint or already cached on the client (also used for sub paintables that are painted later separately)

Throws:

PaintException - if the paint operation failed.

See Also:

PaintTarget.startTag(String)

endPaintable

public void endPaintable(Component paintable)
                  throws PaintException

Description copied from interface: PaintTarget

Prints paintable element end tag. Calls to PaintTarget.startPaintable(Component, String)should be matched by PaintTarget.endPaintable(Component). If the parent tag is closed before every child tag is closed a PaintException is raised.

Specified by:

endPaintable in interface PaintTarget

Parameters:

paintable - the paintable to close.

Throws:

PaintException - if the paint operation failed.

addCharacterData

public void addCharacterData(String text)
                      throws PaintException

Description copied from interface: PaintTarget

Adds CDATA node to target UIDL-tree.

Specified by:

addCharacterData in interface PaintTarget

Parameters:

text - the Character data to add

Throws:

PaintException - if the paint operation failed.

getUsedResources

public Set<Object> getUsedResources()

getTag

public String getTag(ClientConnector clientConnector)

Specified by:

getTag in interface PaintTarget

Returns:

the "tag" string used in communication to present given ClientConnector type. Terminal may define how to present the connector.

getUsedClientConnectors

public Collection<Class<? extends ClientConnector>> getUsedClientConnectors()

addVariable

public void addVariable(VariableOwner owner,
                        String name,
                        StreamVariable value)
                 throws PaintException

Description copied from interface: PaintTarget

Adds details about StreamVariable to the UIDL stream. Eg. in web terminals Receivers are typically rendered for the client side as URLs, where the client side implementation can do an http post request.

The urls in UIDL message may use Vaadin specific protocol. Before actually using the urls on the client side, they should be passed via ApplicationConnection.translateVaadinUri(String).

Note that in current terminal implementation StreamVariables are cleaned from the terminal only when:

• a StreamVariable with same name replaces an old one
• the variable owner is no more attached
• the developer signals this by calling StreamVariable.StreamingStartEvent.disposeStreamVariable()

Most commonly a component developer can just ignore this issue, but with strict memory requirements and lots of StreamVariables implementations that reserve a lot of memory this may be a critical issue.

Specified by:

addVariable in interface PaintTarget

Parameters:

owner - the ReceiverOwner that can track the progress of streaming to the given StreamVariable

name - an identifying name for the StreamVariable

value - the StreamVariable to paint

Throws:

PaintException - if the paint operation failed.

isFullRepaint

public boolean isFullRepaint()

Specified by:

isFullRepaint in interface PaintTarget

Returns:

true if a full repaint has been requested. E.g. refresh in a browser window or such.