ComponentSynchronizePeer


1   /* 
2    * This file is part of the Echo Web Application Framework (hereinafter "Echo").
3    * Copyright (C) 2002-2005 NextApp, Inc.
4    *
5    * Version: MPL 1.1/GPL 2.0/LGPL 2.1
6    *
7    * The contents of this file are subject to the Mozilla Public License Version
8    * 1.1 (the "License"); you may not use this file except in compliance with
9    * the License. You may obtain a copy of the License at
10   * http://www.mozilla.org/MPL/
11   *
12   * Software distributed under the License is distributed on an "AS IS" basis,
13   * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
14   * for the specific language governing rights and limitations under the
15   * License.
16   *
17   * Alternatively, the contents of this file may be used under the terms of
18   * either the GNU General Public License Version 2 or later (the "GPL"), or
19   * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
20   * in which case the provisions of the GPL or the LGPL are applicable instead
21   * of those above. If you wish to allow use of your version of this file only
22   * under the terms of either the GPL or the LGPL, and not to allow others to
23   * use your version of this file under the terms of the MPL, indicate your
24   * decision by deleting the provisions above and replace them with the notice
25   * and other provisions required by the GPL or the LGPL. If you do not delete
26   * the provisions above, a recipient may use your version of this file under
27   * the terms of any one of the MPL, the GPL or the LGPL.
28   */
29  
30  package nextapp.echo2.webcontainer;
31  
32  import nextapp.echo2.app.Component;
33  import nextapp.echo2.app.update.ServerComponentUpdate;
34  
35  /**
36   * A stateless peer object used to synchronize the state of a given type of 
37   * <code>nextapp.echo2.app.Component</code> between the server and client.
38   * <p>
39   * A <code>ComponentSynchronizePeer</code> may implement optional interfaces such as
40   * <code>DomUpdateSupport</code> which enables rendering hierarchies of
41   * components directly to (X)HTML code.  The optional 
42   * <code>ActionProcessor</code> and <code>InputProcessor</code> interfaces
43   * may be used when the client-side rendering of the component may send back
44   * information to the server in response to user input.
45   * <p>
46   * A <b>single</b> instance of a given <code>ComponentSynchronizePeer</code> 
47   * will be created to synchronize the state of <b>ALL</b> instances of 
48   * a particular class of <code>Component</code>.  Thus, it is not possible to
49   * store information about a component's state in this object (in contrast
50   * to Echo v1.x, where a peer was created for each component instance).  Such 
51   * rendering state information should now be stored in the 
52   * <code>ContainerInstance</code>, see the
53   * <code>ContainerInstance.setRenderState()</code> method for details.
54   */
55  public interface ComponentSynchronizePeer {
56      
57      /**
58       * Returns the id of the HTML element in which the specified 
59       * <code>component</code> should be rendered.  The specified
60       * <code>component</code> must be an immediate child of
61       * an instance of the class of component that this peer supports.
62       * A child component's renderer may invoke this method to 
63       * determine where it should place its rendered content.
64       * 
65       * @param child a <code>Component</code> whose parent is of the type
66       *        synchronized by this peer object.
67       * @return the id of the element which should contain the child
68       *         component's rendered HTML.
69       */
70      public String   getContainerId(Component child);
71      
72      /**
73       * Renders a client update which adds an HTML representation of the 
74       * provided component to the client DOM as a child of the HTML element
75       * identified by <code>targetId</code>. 
76       * 
77       * @param rc the relevant <code>RenderContext</code>
78       * @param update the <code>ServerComponentUpdate</code> for which this
79       *        operation is being performed
80       * @param targetId the id of the HTML element in which the component's
81       *        HTML output should be rendered
82       * @param component the component to be rendered (this component must
83       *        be of a type supported by this synchronization peer).
84       */
85      public void renderAdd(RenderContext rc, ServerComponentUpdate update, String   targetId, Component component);
86      
87      /**
88       * Renders a client update to dispose of resources/listeners created
89       * for the specified component on the client.  Operations such as
90       * removing event listeners on the client should be performed by the
91       * implementation.  In cases where no such clean-up work is required, an 
92       * empty implementation is sufficient. Note that the actual removal of 
93       * HTML code will be performed by an ancestor component's 
94       * <code>renderUpdate()</code> method being invoked, and thus 
95       * implementations SHOULD NOT redundantly attempt
96       * to remove the HTML in this method.
97       * Implementations must handle the condition where the component to be
98       * disposed is not present in the client DOM, as this method may be invoked
99       * under such a condition.
100      * 
101      * @param rc the relevant <code>RenderContext</code>
102      * @param update the <code>ServerComponentUpdate</code> for which this
103      *        operation is being performed
104      */
105     public void renderDispose(RenderContext rc, ServerComponentUpdate update, Component component);
106 
107     /**
108      * Renders the specified <code>ServerComponentUpdate</code> by adding and 
109      * removing children and updating properties of the specified 
110      * <code>component</code>.
111      * <p>
112      * If the component is not a container, the implementation only needs to
113      * analyze the updated properties of the component.  If the component is
114      * a container, the implementation should additionally query 
115      * <code>update</code> for information about added children, removed 
116      * children, and children with updated <code>LayoutData</code> states.
117      * <p>
118      * The implementation is responsible for rendering added children by 
119      * obtaining their <code>ComponentSynchronizePeer</code>s and invoking their
120      * <code>renderAdd()</code> methods.  Alternatively, if a child's 
121      * <code>ComponentSynchronizePeer</code> implements the 
122      * <code>DomUpdateSupport</code> interface, the implementation may invoke
123      * the child peer's <code>renderHtml()</code> method instead.
124      * <p>
125      * This method should return true if, in the course of its rendering 
126      * operation, it has re-rendered the entire component hierarchy beneath
127      * the parent component of the update.  Returning true will ensure
128      * that updates to descendants are NOT rendered.  The method should 
129      * return false in all cases if the component is not a container.
130      *
131      * @param rc the relevant <code>RenderContext</code>
132      * @param update the <code>ServerComponentUpdate</code> for which this
133      *        operation is being performed
134      * @param targetId the id of the HTML element inside of which the 
135      *        components HTML code should be rendered.
136      * @return true if updates to descendants should NOT be performed
137      */
138     public boolean renderUpdate(RenderContext rc, ServerComponentUpdate update, String   targetId);
139 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags