KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > enhydra > barracuda > core > forms > FormElement


1 /*
2  * Copyright (C) 2003 Christian Cryder [christianc@granitepeaks.com]
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with this library; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  *
18  * Christian Cryder, Diez B. Roggisch
19  *
20  * $Id: FormElement.java,v 1.16 2004/02/01 05:16:28 christianc Exp $
21  */
22 package org.enhydra.barracuda.core.forms;
23
24 import java.util.*;
25 import javax.servlet.*;
26 import javax.servlet.http.*;
27
28 import org.enhydra.barracuda.plankton.data.DefaultStateMap;
29 import org.enhydra.barracuda.plankton.data.StateMap;
30
31 /**
32  * <p>This interfaces defines the methods a class needs to implement
33  * to act as a FormElement.
34  *
35  * <p>A FormElement defines how an element in a FormMap should
36  * be mapped to a first class java object. There are several
37  * key pieces of information required:
38  *
39  * <ul>
40  * <li>key - used to retrieve the target value from the incoming
41  * data source (either a ServletRequest or a StateMap)</li>
42  * <li>type - the type of data object the incoming value should be
43  * mapped to, as defined by the FormType class (String, Boolean,
44  * Integer, Date, Long, Short, Double, Float)</li>
45  * <li>default val - the default val to be used if the key value is
46  * null in the incoming data source (may be null)</li>
47  * <li>validator - any validators associated with this particular
48  * form elmenent (may be null)</li>
49  * <li>allow multiples - the servlet interface allows multiple params
50  * with the same key. This value indicates whether or not that is
51  * acceptable for a key. If so, then when multiple values are
52  * encountered they element will actually contain a List of values
53  * of the proper type</li>
54  * </ul>
55  *
56  * <p>Once we have this information, we basically have enough data to map
57  * a String value in the data source to a first class Java object in the
58  * element.
59  */
60 public interface FormElement {
61
62     /**
63      * Set the key value for this form element
64      *
65      * @param key the key value for this form element
66      */
67     public void setKey(String JavaDoc key);
68
69     /**
70      * Get the key value for this form element
71      *
72      * @return the key for this form element
73      */
74     public String JavaDoc getKey();
75
76     /**
77      * Set the name of this form element
78      *
79      * @param name the name value of this form element
80      */
81     public void setName(String JavaDoc name);
82
83     /**
84      * Get the name value of form element
85      *
86      * @return the name of this form element
87      */
88     public String JavaDoc getName();
89
90     /**
91      * Set the FormType for this form element
92      *
93      * @param type the FormType for this form element
94      */
95     public void setType(FormType type);
96     
97     /**
98      * Get the FormType for this for element
99      *
100      * @return the FormType for this form element
101      */
102     public FormType getType();
103
104     /**
105      * Set the default value for this form element
106      *
107      * @param defaultVal the FormType for this form element
108      */
109     public void setDefaultVal(Object JavaDoc defaultVal);
110     
111     /**
112      * Get the default value for this form element
113      *
114      * @return the default value for this form element (may be null)
115      */
116     public Object JavaDoc getDefaultVal();
117
118     /**
119      * Set whether or not this element allows multiple values
120      *
121      * @param val true if the element allows multiples
122      */
123     public void setAllowMultiples(boolean val);
124
125     /**
126      * Does this element allow multiple values
127      *
128      * @return true if this element allows multiple values
129      */
130     public boolean allowMultiples();
131
132     /**
133      * Set the FormValidator for this form element
134      *
135      * @param validator the FormValidator for this form element
136      */
137     public void setValidator(FormValidator validator);
138
139     /**
140      * Get the default FormValidator for this form element
141      *
142      * @return the validator for this form element (may be null)
143      */
144     public FormValidator getValidator();
145
146     /**
147      * Set the original value for this element
148      *
149      * @param iorigVal the original value
150      */
151     public void setOrigVal(Object JavaDoc iorigVal);
152
153     /**
154      * Get the original value for this element
155      *
156      * @return the original value for this form element (may be null)
157      */
158     public Object JavaDoc getOrigVal();
159
160     /**
161      * Set the value for this element
162      *
163      * @param ival the value for this element
164      */
165     public void setVal(Object JavaDoc ival);
166
167     /**
168      * Get the value for this element. If the underlying object
169      * is actually an array (ie. allowMultiples = true), then
170      * you should really be calling getVals() to get the whole
171      * object array; if you call this method, you will just get
172      * the first element of the array.
173      *
174      * @return the value for this form element (may be null)
175      */
176     public Object JavaDoc getVal();
177     
178     /**
179      * Get all the values for this element. There will always be an array returned.
180      * if the value for this FormElement is null, an empty array is returned. This
181      * method only really makes sense if allowMultiples = true
182      *
183      * @return the array of values for this form element
184      */
185     public Object JavaDoc[] getVals();
186
187     /**
188      * Get the value for this element as a String
189      */
190     public String JavaDoc getStringVal();
191
192     /**
193      * Get the value for this element as a String, defaulting
194      * accordingly if the value is null
195      */
196     public String JavaDoc getStringVal(String JavaDoc dflt);
197
198     /**
199      * Get the value for this element as a Boolean
200      */
201     public Boolean JavaDoc getBooleanVal();
202
203     /**
204      * Get a Boolean value from the map, defaulting accordingly if
205      * the value is null
206      */
207     public Boolean JavaDoc getBooleanVal(Boolean JavaDoc dflt);
208
209     /**
210      * Get the value for this element as a Integer
211      */
212     public Integer JavaDoc getIntegerVal();
213
214     /**
215      * Get a Integer value from the map, defaulting accordingly if
216      * the value is null
217      */
218     public Integer JavaDoc getIntegerVal(Integer JavaDoc dflt);
219
220     /**
221      * Get the value for this element as a Date
222      */
223     public Date getDateVal();
224
225     /**
226      * Get a Date value from the map, defaulting accordingly if
227      * the value is null
228      */
229     public Date getDateVal(Date dflt);
230
231     /**
232      * Get the value for this element as a Long
233      */
234     public Long JavaDoc getLongVal();
235
236     /**
237      * Get a Long value from the map, defaulting accordingly if
238      * the value is null
239      */
240     public Long JavaDoc getLongVal(Long JavaDoc dflt);
241     
242     /**
243      * Get the value for this element as a Short
244      */
245     public Short JavaDoc getShortVal();
246
247     /**
248      * Get a Short value from the map, defaulting accordingly if
249      * the value is null
250      */
251     public Short JavaDoc getShortVal(Short JavaDoc dflt);
252
253     /**
254      * Get the value for this element as a Double
255      */
256     public Double JavaDoc getDoubleVal();
257
258     /**
259      * Get a Double value from the map, defaulting accordingly if
260      * the value is null
261      */
262     public Double JavaDoc getDoubleVal(Double JavaDoc dflt);
263
264     /**
265      * Get the value for this element as a Float
266      */
267     public Float JavaDoc getFloatVal();
268
269     /**
270      * Get a Float value from the map, defaulting accordingly if
271      * the value is null
272      */
273     public Float JavaDoc getFloatVal(Float JavaDoc dflt);
274
275     /**
276      * Set the parse exception associated with this element
277      *
278      * @return any parse exceptions associated with the element
279      */
280     public void setParseException(ParseException pe);
281
282     /**
283      * Get any parse exceptions associated with the element (ie. that
284      * might have occurred when the element was mapped)
285      *
286      * @return any parse exceptions associated with the element
287      */
288     public ParseException getParseException();
289     
290
291
292
293 //I don't think these are needed if we go back to the older/terser naming convention
294
295
296     /**
297      * Get the value for this element. If the elment has multiple values, the
298      * first is returned.
299      *
300      * @return the value for this form element (may be null)
301      */
302 // public Object getSingleValue();
303
304
305     /**
306      * Get the values for this element. There will always be an array returned, even if
307      * the value for this FormElement is null - then an empty array is returned.
308      *
309      * @return the array of values for this form element
310      */
311
312 // public Object [] getMultipleValues();
313
314     /**
315      * @clientCardinality 1
316      */
317     /*#FormValidator lnkFormValidator;*/
318 }
319
Popular Tags