Package com.vaadin.server

Interface PaintTarget

All Superinterfaces:

Serializable

All Known Implementing Classes:

JsonPaintTarget

public interface PaintTarget
extends Serializable

This interface defines the methods for painting XML to the UIDL stream.

Since:

3.0

Author:

Vaadin Ltd.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	PaintTarget.PaintStatus	Result of starting to paint a Component ( startPaintable(Component, String)).

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 string, Object[] keys)
void	addAttribute(String name, String value)	Adds a string attribute to component.
void	addAttribute(String name, Map<?,?> value)	Adds a Map attribute to the component.
void	addCharacterData(String text)	Adds CDATA node to target UIDL-tree.
void	addSection(String sectionTagName, String sectionData)	Prints single XMLsection.
void	addText(String text)	Adds text node.
void	addUIDL(String uidl)	Adds UIDL directly.
void	addUploadStreamVariable(VariableOwner owner, String name)	Adds an 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 an 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)	Prints single XML section.
void	endPaintable(Component paintable)	Prints paintable element end tag.
void	endTag(String tagName)	Prints element end tag.
String	getTag(ClientConnector paintable)
boolean	isFullRepaint()
PaintTarget.PaintStatus	startPaintable(Component paintable, String tag)	Prints element start tag of a paintable section.
void	startTag(String tagName)	Prints element start tag.

Method Detail

addSection

void addSection(String sectionTagName,
                String sectionData)
         throws PaintException

Prints single XMLsection. Prints full XML section. The section data is escaped from XML tags and surrounded by XML start and end-tags.

Parameters:

sectionTagName - the name of the tag.

sectionData - the section data.

Throws:

PaintException - if the paint operation failed.

startPaintable

PaintTarget.PaintStatus startPaintable(Component paintable,
                                       String tag)
                                throws PaintException

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 endPaintable(Component) regardless of the PaintTarget.PaintStatus returned.

Parameters:

paintable - the paintable to start.

tag - 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.

Since:

7.0 (previously using startTag(Paintable, String))

See Also:

startTag(String)

endPaintable

void endPaintable(Component paintable)
           throws PaintException

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

Parameters:

paintable - the paintable to close.

Throws:

PaintException - if the paint operation failed.

Since:

7.0 (previously using engTag(String))

startTag

void startTag(String tagName)
       throws PaintException

Prints element start tag.

 Todo:
 Checking of input values
 

Parameters:

tagName - the name of the start tag.

Throws:

PaintException - if the paint operation failed.

endTag

void endTag(String tagName)
     throws PaintException

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

Parameters:

tagName - the name of the end tag.

Throws:

PaintException - if the paint operation failed.

addAttribute

void addAttribute(String name,
                  boolean value)
           throws PaintException

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

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

void addAttribute(String name,
                  int value)
           throws PaintException

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

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

void addAttribute(String name,
                  Resource value)
           throws PaintException

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

Parameters:

name - the Attribute name

value - the Attribute value

Throws:

PaintException - if the paint operation failed.

addVariable

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

Adds details about StreamVariable to the UIDL stream. E.g. 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 com.vaadin.client.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.

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.

addAttribute

void addAttribute(String name,
                  long value)
           throws PaintException

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

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

void addAttribute(String name,
                  float value)
           throws PaintException

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

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

void addAttribute(String name,
                  double value)
           throws PaintException

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

Parameters:

name - the Attribute name.

value - the Attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

void addAttribute(String name,
                  String value)
           throws PaintException

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

Parameters:

name - the Boolean attribute name.

value - the Boolean attribute value.

Throws:

PaintException - if the paint operation failed.

addAttribute

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

Adds a Map attribute to the component. Attributes must be added before any content is written. TODO: specify how the map is added

Parameters:

name -

value -

Throws:

PaintException

addAttribute

void addAttribute(String name,
                  Component value)
           throws PaintException

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

Parameters:

name - the name of the attribute

value - the Component to be referenced on client side

Throws:

PaintException

addVariable

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

Adds a string type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

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

Adds an int type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

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

Adds a long type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

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

Adds a float type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

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

Adds a double type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

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

Adds a boolean type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

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

Adds a string array type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

value - the Variable initial value.

Throws:

PaintException - if the paint operation failed.

addVariable

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

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.

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

addUploadStreamVariable

void addUploadStreamVariable(VariableOwner owner,
                             String name)
                      throws PaintException

Adds an upload stream type variable.

Parameters:

owner - the Listener for variable changes.

name - the Variable name.

Throws:

PaintException - if the paint operation failed.

addXMLSection

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

Prints single XML section.

Prints full XML section. The section data must be XML and it is surrounded by XML start and end-tags.

Parameters:

sectionTagName - the tag name.

sectionData - the section data to be printed.

namespace - the namespace.

Throws:

PaintException - if the paint operation failed.

addUIDL

void addUIDL(String uidl)
      throws PaintException

Adds UIDL directly. The UIDL must be valid in accordance with the UIDL.dtd

Parameters:

uidl - the UIDL to be added.

Throws:

PaintException - if the paint operation failed.

addText

void addText(String text)
      throws PaintException

Adds text node. All the contents of the text are XML-escaped.

Parameters:

text - the Text to add

Throws:

PaintException - if the paint operation failed.

addCharacterData

void addCharacterData(String text)
               throws PaintException

Adds CDATA node to target UIDL-tree.

Parameters:

text - the Character data to add

Throws:

PaintException - if the paint operation failed.

Since:

3.1

addAttribute

void addAttribute(String string,
                  Object[] keys)

getTag

String getTag(ClientConnector paintable)

Returns:

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

isFullRepaint

boolean isFullRepaint()

Returns:

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