123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516 |
- /*
- * 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.server;
-
- import java.io.Serializable;
- import java.util.Map;
-
- import com.vaadin.server.StreamVariable.StreamingStartEvent;
- import com.vaadin.ui.Component;
-
- /**
- * This interface defines the methods for painting XML to the UIDL stream.
- *
- * @author Vaadin Ltd.
- * @since 3.0
- */
- public interface PaintTarget extends Serializable {
-
- /**
- * Prints single XMLsection.
- *
- * Prints full XML section. The section data is escaped from XML tags and
- * surrounded by XML start and end-tags.
- *
- * @param sectionTagName
- * the name of the tag.
- * @param sectionData
- * the scetion data.
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addSection(String sectionTagName, String sectionData)
- throws PaintException;
-
- /**
- * Result of starting to paint a Component (
- * {@link PaintTarget#startPaintable(Component, String)}).
- *
- * @since 7.0
- */
- public enum PaintStatus {
- /**
- * Painting started, addVariable() and addAttribute() etc. methods may
- * be called.
- */
- PAINTING,
- /**
- * A previously unpainted or painted {@link Component} has been queued
- * be created/update later in a separate change in the same set of
- * changes.
- */
- CACHED
- }
-
- /**
- * 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.
- * <p>
- * If the {@link 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.
- * </p>
- * <p>
- * This method may also add only a reference to the paintable and queue the
- * paintable to be painted separately.
- * </p>
- * <p>
- * Each paintable being painted should be closed by a matching
- * {@link #endPaintable(Component)} regardless of the {@link PaintStatus}
- * returned.
- * </p>
- *
- * @param paintable
- * the paintable to start.
- * @param tag
- * the name of the start tag.
- * @return {@link 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 #startTag(String)
- * @since 7.0 (previously using startTag(Paintable, String))
- */
- public PaintStatus startPaintable(Component paintable, String tag)
- throws PaintException;
-
- /**
- * Prints paintable element end tag.
- *
- * Calls to {@link #startPaintable(Component, String)}should be matched by
- * {@link #endPaintable(Component)}. If the parent tag is closed before
- * every child tag is closed a PaintException is raised.
- *
- * @param paintable
- * the paintable to close.
- * @throws PaintException
- * if the paint operation failed.
- * @since 7.0 (previously using engTag(String))
- */
- public void endPaintable(Component paintable) throws PaintException;
-
- /**
- * Prints element start tag.
- *
- * <pre>
- * Todo:
- * Checking of input values
- * </pre>
- *
- * @param tagName
- * the name of the start tag.
- * @throws PaintException
- * if the paint operation failed.
- */
- public void startTag(String tagName) throws PaintException;
-
- /**
- * Prints element end tag.
- *
- * If the parent tag is closed before every child tag is closed an
- * PaintException is raised.
- *
- * @param tagName
- * the name of the end tag.
- * @throws PaintException
- * if the paint operation failed.
- */
- public void endTag(String tagName) throws PaintException;
-
- /**
- * Adds a boolean attribute to component. Atributes must be added before any
- * content is written.
- *
- * @param name
- * the Attribute name.
- * @param value
- * the Attribute value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addAttribute(String name, boolean value) throws PaintException;
-
- /**
- * Adds a integer attribute to component. Atributes must be added before any
- * content is written.
- *
- * @param name
- * the Attribute name.
- * @param value
- * the Attribute value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addAttribute(String name, int value) throws PaintException;
-
- /**
- * Adds a resource attribute to component. Atributes must be added before
- * any content is written.
- *
- * @param name
- * the Attribute name
- * @param value
- * the Attribute value
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addAttribute(String name, Resource value) throws PaintException;
-
- /**
- * Adds details about {@link 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.
- * <p>
- * The urls in UIDL message may use Vaadin specific protocol. Before
- * actually using the urls on the client side, they should be passed via
- * {@link com.vaadin.client.ApplicationConnection#translateVaadinUri(String)}.
- * <p>
- * Note that in current terminal implementation StreamVariables are cleaned
- * from the terminal only when:
- * <ul>
- * <li>a StreamVariable with same name replaces an old one
- * <li>the variable owner is no more attached
- * <li>the developer signals this by calling
- * {@link StreamingStartEvent#disposeStreamVariable()}
- * </ul>
- * 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.
- *
- * @param owner
- * the ReceiverOwner that can track the progress of streaming to
- * the given StreamVariable
- * @param name
- * an identifying name for the StreamVariable
- * @param value
- * the StreamVariable to paint
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name,
- StreamVariable value) throws PaintException;
-
- /**
- * Adds a long attribute to component. Atributes must be added before any
- * content is written.
- *
- * @param name
- * the Attribute name.
- * @param value
- * the Attribute value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addAttribute(String name, long value) throws PaintException;
-
- /**
- * Adds a float attribute to component. Atributes must be added before any
- * content is written.
- *
- * @param name
- * the Attribute name.
- * @param value
- * the Attribute value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addAttribute(String name, float value) throws PaintException;
-
- /**
- * Adds a double attribute to component. Atributes must be added before any
- * content is written.
- *
- * @param name
- * the Attribute name.
- * @param value
- * the Attribute value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addAttribute(String name, double value) throws PaintException;
-
- /**
- * Adds a string attribute to component. Atributes must be added before any
- * content is written.
- *
- * @param name
- * the Boolean attribute name.
- * @param value
- * the Boolean attribute value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addAttribute(String name, String value) throws PaintException;
-
- /**
- * TODO
- *
- * @param name
- * @param value
- * @throws PaintException
- */
- public void addAttribute(String name, Map<?, ?> 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.
- *
- * @param name
- * the name of the attribute
- * @param value
- * the Component to be referenced on client side
- * @throws PaintException
- */
- public void addAttribute(String name, Component value)
- throws PaintException;
-
- /**
- * Adds a string type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- * @param value
- * the Variable initial value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name, String value)
- throws PaintException;
-
- /**
- * Adds a int type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- * @param value
- * the Variable initial value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name, int value)
- throws PaintException;
-
- /**
- * Adds a long type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- * @param value
- * the Variable initial value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name, long value)
- throws PaintException;
-
- /**
- * Adds a float type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- * @param value
- * the Variable initial value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name, float value)
- throws PaintException;
-
- /**
- * Adds a double type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- * @param value
- * the Variable initial value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name, double value)
- throws PaintException;
-
- /**
- * Adds a boolean type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- * @param value
- * the Variable initial value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name, boolean value)
- throws PaintException;
-
- /**
- * Adds a string array type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- * @param value
- * the Variable initial value.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addVariable(VariableOwner owner, String name, String[] 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.
- *
- * @param owner
- * the Listener for variable changes
- * @param name
- * the name of the variable
- * @param value
- * the initial value of the variable
- *
- * @throws PaintException
- * if the paint oparation fails
- */
- public void addVariable(VariableOwner owner, String name, Component value)
- throws PaintException;
-
- /**
- * Adds a upload stream type variable.
- *
- * @param owner
- * the Listener for variable changes.
- * @param name
- * the Variable name.
- *
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addUploadStreamVariable(VariableOwner owner, String name)
- throws PaintException;
-
- /**
- * Prints single XML section.
- * <p>
- * Prints full XML section. The section data must be XML and it is
- * surrounded by XML start and end-tags.
- * </p>
- *
- * @param sectionTagName
- * the tag name.
- * @param sectionData
- * the section data to be printed.
- * @param namespace
- * the namespace.
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addXMLSection(String sectionTagName, String sectionData,
- String namespace) throws PaintException;
-
- /**
- * Adds UIDL directly. The UIDL must be valid in accordance with the
- * UIDL.dtd
- *
- * @param uidl
- * the UIDL to be added.
- * @throws PaintException
- * if the paint operation failed.
- */
- public void addUIDL(java.lang.String uidl) throws PaintException;
-
- /**
- * Adds text node. All the contents of the text are XML-escaped.
- *
- * @param text
- * the Text to add
- * @throws PaintException
- * if the paint operation failed.
- */
- void addText(String text) throws PaintException;
-
- /**
- * Adds CDATA node to target UIDL-tree.
- *
- * @param text
- * the Character data to add
- * @throws PaintException
- * if the paint operation failed.
- * @since 3.1
- */
- void addCharacterData(String text) throws PaintException;
-
- public void addAttribute(String string, Object[] keys);
-
- /**
- * @return the "tag" string used in communication to present given
- * {@link ClientConnector} type. Terminal may define how to present
- * the connector.
- */
- public String getTag(ClientConnector paintable);
-
- /**
- * @return true if a full repaint has been requested. E.g. refresh in a
- * browser window or such.
- */
- public boolean isFullRepaint();
-
- }
|