Widget


1   /*
2    * Copyright 1999-2004 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.woody.formmodel;
17  
18  import org.apache.cocoon.woody.FormContext;
19  import org.apache.cocoon.woody.event.WidgetEvent;
20  import org.xml.sax.ContentHandler  ;
21  import org.xml.sax.SAXException  ;
22  
23  import java.util.Locale  ;
24  
25  /**
26   * Interface to be implemented by Widgets. In Woody, a form consists of a number
27   * of widgets. Each widget:
28   *
29   * <ul>
30   *  <li>has an id, unique within its parent context widget. See {@link #getId()}.</li>
31   *  <li>can have children (see {@link #getWidget(String)}, and can have a parent (see {@link #getParent()}.</li>
32   *  <li>can hold a value (which can be any kind of object). See {@link #getValue()}.</li>
33   *  <li>can read its value from a request object (and convert it from a string to its native type).
34   *  See {@link #readFromRequest(FormContext)}.</li>
35   *  <li>can validate itself. See {@link #validate(FormContext)}.</li>
36   *  <li>can generate an XML representation of itself.</li>
37   * </ul>
38   *
39   * <p>Because widgets can have children, the widgets form a widget tree, with its root
40   * being the {@link Form} widget.</p>
41   *
42   * <p>A widget can have only a value, or only child widgets, or can have both a value and child
43   * widgets, or can have neither. This all depends on the widget implementation.</p>
44   *
45   * <p>When a request is submitted, first the {@link #readFromRequest(FormContext)} method of all widgets
46   * will be called so that they can read their value(s). Next, the {@link #validate(FormContext)} method will
47   * be called. Doing this in two steps allows the validation to compare values between widgets.
48   * See also the method {@link Form#process(FormContext)}.</p>
49   *
50   * <p>A Widget is created by calling the createInstance method on the a
51   * {@link WidgetDefinition}. A Widget holds all the data that is specific for
52   * a certain use of the widget (its value, validationerrors, ...), while the
53   * WidgetDefinition holds the data that is static accross all widgets. This
54   * keeps the Widgets small and light to create. This mechanism is similar to
55   * classes and objects in Java.
56   * 
57   * @version CVS $Id: Widget.java 30932 2004-07-29 17:35:38Z vgritsenko $
58   */
59  public interface Widget {
60  
61      /**
62       * Gets the source location of this widget.
63       */
64      public String   getLocation();
65  
66      /**
67       * Returns the id of this widget.
68       */
69      public String   getId();
70  
71      /**
72       * Gets the parent of this widget. If this widget is the root widget,
73       * this method returns null.
74       */
75      public Widget getParent();
76  
77      /**
78       * This method is called on a widget when it is added to a container.
79       * You shouldn't call this method unless youre implementing a widget yourself (in
80       * which case it should be called when a widget is added as child of your widget).
81       */
82      public void setParent(Widget widget);
83      
84      /**
85       * Get the {@link Form} to which this widget belongs. The form is the top-most ancestor
86       * of the widget.
87       */
88      public Form getForm();
89  
90      /**
91       * Gets the namespace of this widget. The combination of a widget's namespace
92       * with its id (see {@link #getId()} gives the widget a form-wide unique name.
93       * In practice, the namespace consists of the id's of the widget's parent widgets,
94       * separated by dots.
95       */
96      public String   getNamespace();
97  
98      /**
99       * Returns the id prefixed with the namespace, this name should be unique
100      * accross all widgets on the form.
101      */
102     public String   getFullyQualifiedId();
103 
104     /**
105      * Lets this widget read its data from a request. At this point the Widget
106      * may try to convert the request parameter to its native datatype (if it
107      * is not a string), but it should not yet generate any validation errors.
108      */
109     public void readFromRequest(FormContext formContext);
110 
111     /**
112      * Validates this widget and returns the outcome. Possible error messages are
113      * remembered by the widget itself and will be part of the XML produced by
114      * this widget in its {@link #generateSaxFragment(ContentHandler, Locale)} method.
115      */
116     public boolean validate(FormContext formContext);
117 
118     /**
119      * Generates an XML representation of this widget. The startDocument and endDocument
120      * SAX events will not be called. It is assumed that the prefix for the Woody namespace
121      * mentioned in Constants.WI_PREFIX is already declared (by the caller or otherwise).
122      */
123     public void generateSaxFragment(ContentHandler   contentHandler, Locale   locale) throws SAXException  ;
124 
125     /**
126      * Generates SAX events for the label of this widget. The label will not be wrapped
127      * inside another element.
128      */
129     public void generateLabel(ContentHandler   contentHandler) throws SAXException  ;
130 
131     /**
132      * Returns the value of the widget. For some widgets (notably ContainerWidgets)
133      * this may not make sense, those should then simply return null here.
134      */
135     public Object   getValue();
136     
137     /**
138      * Sets the value of this widget to the given object. Some widgets may not support this
139      * method, those should throw an runtime exception if you try to set their value anyway.
140      */
141     public void setValue(Object   object);
142 
143     /**
144      * Returns wether this widget is required to be filled in. As with {@link #getValue()}, for some
145      * widgets this may not make sense, those should return false here.
146      */
147     public boolean isRequired();
148 
149     /**
150      * Gets the child widget of this widget with the given id, or null if there isn't such a child.
151      */
152     public Widget getWidget(String   id);
153     
154     /**
155      * Broadcast an event previously queued by this widget to its event listeners.
156      */
157     public void broadcastEvent(WidgetEvent event);
158 }
159
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags