Widget


1   /*
2    * Copyright 1999-2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.forms.formmodel;
17  
18  import org.apache.cocoon.forms.FormContext;
19  import org.apache.cocoon.forms.validation.WidgetValidator;
20  import org.apache.cocoon.forms.event.WidgetEvent;
21  import org.apache.cocoon.util.location.Locatable;
22  import org.apache.cocoon.util.location.Location;
23  import org.xml.sax.ContentHandler  ;
24  import org.xml.sax.SAXException  ;
25  
26  import java.util.Locale  ;
27  
28  /**
29   * Interface to be implemented by Widgets. In CForms, a form consists of a number
30   * of widgets. Each widget:
31   *
32   * <ul>
33   *  <li>has an id, unique within its parent context widget. See {@link #getId()}.</li>
34   *  <li>can have a parent (see {@link #getParent()}.</li>
35   *  <li>can hold a value (which can be any kind of object). See {@link #getValue()}.</li>
36   *  <li>can read its value from a request object (and convert it from a string to its native type).
37   *  See {@link #readFromRequest(FormContext)}.</li>
38   *  <li>can validate itself. See {@link #validate()}.</li>
39   *  <li>can generate an XML representation of itself.</li>
40   * </ul>
41   *
42   * <p>When a request is submitted, first the {@link #readFromRequest(FormContext)} method of all widgets
43   * will be called so that they can read their value(s). Next, the {@link #validate()} method will
44   * be called. Doing this in two steps allows the validation to compare values between widgets.
45   * See also the method {@link Form#process(FormContext)}.</p>
46   *
47   * <p>A Widget is created by calling the createInstance method on the a
48   * {@link WidgetDefinition}. A Widget holds all the data that is specific for
49   * a certain use of the widget (its value, validationerrors, ...), while the
50   * WidgetDefinition holds the data that is static accross all widgets. This
51   * keeps the Widgets small and light to create. This mechanism is similar to
52   * classes and objects in Java.
53   *
54   * @version $Id: Widget.java 289538 2005-09-16 13:46:22Z sylvain $
55   */
56  public interface Widget extends Locatable {
57  
58      /**
59       * Widget-Separator used in path-like notations
60       * @see #lookupWidget(String)
61       */
62      char PATH_SEPARATOR = '/';
63  
64      /**
65       * Called after widget's environment has been setup,
66       * to allow for any contextual initalization such as
67       * looking up case widgets for union widgets.
68       */
69      void initialize();
70  
71      /**
72       * @return  the source location of this widget.
73       */
74      Location getLocation();
75  
76      /**
77       * @return the name of this widget.  This should never be <code>null</code>
78       * Top-level container widgets (like 'form') should return <code>""</code>
79       */
80      String   getName();
81  
82      /**
83       * @return the id of this widget.  This should never be <code>null</code>
84       * Top-level container widgets (like 'form') should return <code>""</code>
85       */
86      String   getId();
87  
88      /**
89       * @return the parent of this widget. If this widget is the root widget,
90       * this method returns null.
91       */
92      Widget getParent();
93  
94      /**
95       * This method is called on a widget when it is added to a container.
96       * You shouldn't call this method unless youre implementing a widget yourself (in
97       * which case it should be called when a widget is added as child of your widget).
98       */
99      void setParent(Widget widget);
100 
101     /**
102      * @return the {@link Form} to which this widget belongs. The form is the top-most ancestor
103      * of the widget.
104      */
105     Form getForm();
106 
107     /**
108      * Get this widget's definition.
109      *
110      * @return the widget's definition
111      */
112     WidgetDefinition getDefinition();
113     
114     /**
115      * Get the widget's own state. Note that this state is <em>not</em> the one actually considered
116      * for handling requests and producing output. For these matters, the combined state is used.
117      *
118      * @see #getCombinedState()
119      * @return the widget's own state
120      */
121     WidgetState getState();
122 
123     /**
124      * Set the widget's own state. This may change its combined state, and those of its
125      * children, if any.
126      *
127      * @param state the new wiget state
128      */
129     void setState(WidgetState state);
130 
131     /**
132      * Get the widget's combined state, which is the strictest of its own state and parent state.
133      * This combined state is the one that will be used by the widget to know if request
134      * parameters should be considered and if some output must be produced.
135      *
136      * @see WidgetState#strictest(WidgetState, WidgetState)
137      * @return the combined state
138      */
139     WidgetState getCombinedState();
140 
141     /**
142      * @return the name prefixed with the namespace, this name should be unique
143      * accross all widgets on the form.
144      */
145     String   getFullName();
146 
147     /**
148      * @return the id prefixed with the namespace, this name should be unique
149      * accross all widgets on the form.
150      */
151     String   getRequestParameterName();
152 
153     /**
154      * @deprecated getWidget got removed, use lookupWidget or getChild instead.
155      * @throws UnsupportedOperationException indicating this method has been
156      * deprecated from the API, and will be removed from future releases.
157      */
158     Widget getWidget(String   id);
159 
160     /**
161      * Finds a widget relative to this one based on a path-like
162      * string (/-delimted) into the widget-tree structure.
163      * This supports '../' and '/' to point to
164      * @return the found widget or <code>null</code> if allong the traversal
165      *   of the path an invalid section was encountered.
166      */
167     Widget lookupWidget(String   path);
168 
169     /**
170      * Lets this widget read its data from a request. At this point the Widget
171      * may try to convert the request parameter to its native datatype (if it
172      * is not a string), but it should not yet generate any validation errors.
173      */
174     void readFromRequest(FormContext formContext);
175 
176     /**
177      * Validates this widget and returns the outcome. Possible error messages are
178      * remembered by the widget itself and will be part of the XML produced by
179      * this widget in its {@link #generateSaxFragment(ContentHandler, Locale)} method.
180      *
181      * @return <code>true</code> to indicate all validations were ok,
182      *         <code>false</code> otherwise
183      */
184     boolean validate();
185 
186     void addValidator(WidgetValidator validator);
187 
188     boolean removeValidator(WidgetValidator validator);
189 
190     /**
191      * Return the current validation state.
192      * This method delivers the same result as the last call to {@link #validate()}.
193      * The validation process is not started again. If the value of this widget has
194      * changed since the latest call to {@link #validate()}, the result of this method
195      * is out of date.
196      * @return The result of the last call to {@link #validate()}.
197      */
198     boolean isValid();
199 
200     /**
201      * Generates an XML representation of this widget. The startDocument and endDocument
202      * SAX events will not be called. It is assumed that the prefix for the CForms namespace
203      * mentioned in Constants.FI_PREFIX is already declared (by the caller or otherwise).
204      */
205     void generateSaxFragment(ContentHandler   contentHandler, Locale   locale) throws SAXException  ;
206 
207     /**
208      * Generates SAX events for the label of this widget. The label will not be wrapped
209      * inside another element.
210      */
211     void generateLabel(ContentHandler   contentHandler) throws SAXException  ;
212 
213     /**
214      * Get the value of a widget.
215      * <p>
216      * Not all widgets do have a value (notably {@link ContainerWidget}s,
217      * but this method is provided here as a convenience to ease writing and avoiding casts.
218      *
219      * @return the value of the widget.
220      * @throws UnsupportedOperationException if this widget doesn't have a value.
221      */
222     Object   getValue() throws UnsupportedOperationException  ;
223 
224     /**
225      * Sets the value of this widget.
226      * <p>
227      * Not all widgets do have a value (notably {@link ContainerWidget}s,
228      * but this method is provided here as a convenience to ease writing and avoiding casts.
229      *
230      * @param value the new widget's value.
231      * @throws UnsupportedOperationException if this widget doesn't have a value.
232      */
233     void setValue(Object   value) throws UnsupportedOperationException  ;
234 
235     /**
236      * @return whether this widget is required to be filled in. As with {@link #getValue()},
237      * for some widgets this may not make sense, those should return false here.
238      */
239     boolean isRequired();
240 
241     /**
242      * Broadcast an event previously queued by this widget to its event listeners.
243      */
244     void broadcastEvent(WidgetEvent event);
245 
246     /**
247      * Retrieves an attribute on this widget.
248      *
249      * @param name of the attribute to lookup
250      * @return the found attribute or <code>null</code> if none was found with that name.
251      */
252     Object   getAttribute(String   name);
253 
254     /**
255      * Sets an attribute on this widget. This can be used to store custom
256      * data with each widget.
257      */
258     void setAttribute(String   name, Object   value);
259 
260     /**
261      * Removes the named attribute from this widget.
262      *
263      * @param name of the attribute
264      */
265     void removeAttribute(String   name);
266 }
267
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags