001: /*
002: * This file is part of the Echo Web Application Framework (hereinafter "Echo").
003: * Copyright (C) 2002-2005 NextApp, Inc.
004: *
005: * Version: MPL 1.1/GPL 2.0/LGPL 2.1
006: *
007: * The contents of this file are subject to the Mozilla Public License Version
008: * 1.1 (the "License"); you may not use this file except in compliance with
009: * the License. You may obtain a copy of the License at
010: * http://www.mozilla.org/MPL/
011: *
012: * Software distributed under the License is distributed on an "AS IS" basis,
013: * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
014: * for the specific language governing rights and limitations under the
015: * License.
016: *
017: * Alternatively, the contents of this file may be used under the terms of
018: * either the GNU General Public License Version 2 or later (the "GPL"), or
019: * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
020: * in which case the provisions of the GPL or the LGPL are applicable instead
021: * of those above. If you wish to allow use of your version of this file only
022: * under the terms of either the GPL or the LGPL, and not to allow others to
023: * use your version of this file under the terms of the MPL, indicate your
024: * decision by deleting the provisions above and replace them with the notice
025: * and other provisions required by the GPL or the LGPL. If you do not delete
026: * the provisions above, a recipient may use your version of this file under
027: * the terms of any one of the MPL, the GPL or the LGPL.
028: */
029:
030: package nextapp.echo2.webcontainer;
031:
032: import nextapp.echo2.app.Component;
033: import nextapp.echo2.app.update.ServerComponentUpdate;
034:
035: /**
036: * A stateless peer object used to synchronize the state of a given type of
037: * <code>nextapp.echo2.app.Component</code> between the server and client.
038: * <p>
039: * A <code>ComponentSynchronizePeer</code> may implement optional interfaces such as
040: * <code>DomUpdateSupport</code> which enables rendering hierarchies of
041: * components directly to (X)HTML code. The optional
042: * <code>ActionProcessor</code> and <code>InputProcessor</code> interfaces
043: * may be used when the client-side rendering of the component may send back
044: * information to the server in response to user input.
045: * <p>
046: * A <b>single</b> instance of a given <code>ComponentSynchronizePeer</code>
047: * will be created to synchronize the state of <b>ALL</b> instances of
048: * a particular class of <code>Component</code>. Thus, it is not possible to
049: * store information about a component's state in this object (in contrast
050: * to Echo v1.x, where a peer was created for each component instance). Such
051: * rendering state information should now be stored in the
052: * <code>ContainerInstance</code>, see the
053: * <code>ContainerInstance.setRenderState()</code> method for details.
054: */
055: public interface ComponentSynchronizePeer {
056:
057: /**
058: * Returns the id of the HTML element in which the specified
059: * <code>component</code> should be rendered. The specified
060: * <code>component</code> must be an immediate child of
061: * an instance of the class of component that this peer supports.
062: * A child component's renderer may invoke this method to
063: * determine where it should place its rendered content.
064: *
065: * @param child a <code>Component</code> whose parent is of the type
066: * synchronized by this peer object.
067: * @return the id of the element which should contain the child
068: * component's rendered HTML.
069: */
070: public String getContainerId(Component child);
071:
072: /**
073: * Renders a client update which adds an HTML representation of the
074: * provided component to the client DOM as a child of the HTML element
075: * identified by <code>targetId</code>.
076: *
077: * @param rc the relevant <code>RenderContext</code>
078: * @param update the <code>ServerComponentUpdate</code> for which this
079: * operation is being performed
080: * @param targetId the id of the HTML element in which the component's
081: * HTML output should be rendered
082: * @param component the component to be rendered (this component must
083: * be of a type supported by this synchronization peer).
084: */
085: public void renderAdd(RenderContext rc,
086: ServerComponentUpdate update, String targetId,
087: Component component);
088:
089: /**
090: * Renders a client update to dispose of resources/listeners created
091: * for the specified component on the client. Operations such as
092: * removing event listeners on the client should be performed by the
093: * implementation. In cases where no such clean-up work is required, an
094: * empty implementation is sufficient. Note that the actual removal of
095: * HTML code will be performed by an ancestor component's
096: * <code>renderUpdate()</code> method being invoked, and thus
097: * implementations SHOULD NOT redundantly attempt
098: * to remove the HTML in this method.
099: * Implementations must handle the condition where the component to be
100: * disposed is not present in the client DOM, as this method may be invoked
101: * under such a condition.
102: *
103: * @param rc the relevant <code>RenderContext</code>
104: * @param update the <code>ServerComponentUpdate</code> for which this
105: * operation is being performed
106: */
107: public void renderDispose(RenderContext rc,
108: ServerComponentUpdate update, Component component);
109:
110: /**
111: * Renders the specified <code>ServerComponentUpdate</code> by adding and
112: * removing children and updating properties of the specified
113: * <code>component</code>.
114: * <p>
115: * If the component is not a container, the implementation only needs to
116: * analyze the updated properties of the component. If the component is
117: * a container, the implementation should additionally query
118: * <code>update</code> for information about added children, removed
119: * children, and children with updated <code>LayoutData</code> states.
120: * <p>
121: * The implementation is responsible for rendering added children by
122: * obtaining their <code>ComponentSynchronizePeer</code>s and invoking their
123: * <code>renderAdd()</code> methods. Alternatively, if a child's
124: * <code>ComponentSynchronizePeer</code> implements the
125: * <code>DomUpdateSupport</code> interface, the implementation may invoke
126: * the child peer's <code>renderHtml()</code> method instead.
127: * <p>
128: * This method should return true if, in the course of its rendering
129: * operation, it has re-rendered the entire component hierarchy beneath
130: * the parent component of the update. Returning true will ensure
131: * that updates to descendants are NOT rendered. The method should
132: * return false in all cases if the component is not a container.
133: *
134: * @param rc the relevant <code>RenderContext</code>
135: * @param update the <code>ServerComponentUpdate</code> for which this
136: * operation is being performed
137: * @param targetId the id of the HTML element inside of which the
138: * components HTML code should be rendered.
139: * @return true if updates to descendants should NOT be performed
140: */
141: public boolean renderUpdate(RenderContext rc,
142: ServerComponentUpdate update, String targetId);
143: }
|