Java > Open Source Codes > com > jcorporate > expresso > core > controller > Input


1 /* ====================================================================
2  * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
3  *
4  * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  *
13  * 2. Redistributions in binary form must reproduce the above copyright
14  * notice, this list of conditions and the following disclaimer in
15  * the documentation and/or other materials provided with the
16  * distribution.
17  *
18  * 3. The end-user documentation included with the redistribution,
19  * if any, must include the following acknowledgment:
20  * "This product includes software developed by Jcorporate Ltd.
21  * (http://www.jcorporate.com/)."
22  * Alternately, this acknowledgment may appear in the software itself,
23  * if and wherever such third-party acknowledgments normally appear.
24  *
25  * 4. "Jcorporate" and product names such as "Expresso" must
26  * not be used to endorse or promote products derived from this
27  * software without prior written permission. For written permission,
28  * please contact info@jcorporate.com.
29  *
30  * 5. Products derived from this software may not be called "Expresso",
31  * or other Jcorporate product names; nor may "Expresso" or other
32  * Jcorporate product names appear in their name, without prior
33  * written permission of Jcorporate Ltd.
34  *
35  * 6. No product derived from this software may compete in the same
36  * market space, i.e. framework, without prior written permission
37  * of Jcorporate Ltd. For written permission, please contact
38  * partners@jcorporate.com.
39  *
40  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43  * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
44  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
45  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
46  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51  * SUCH DAMAGE.
52  * ====================================================================
53  *
54  * This software consists of voluntary contributions made by many
55  * individuals on behalf of the Jcorporate Ltd. Contributions back
56  * to the project(s) are encouraged when you make modifications.
57  * Please send them to support@jcorporate.com. For more information
58  * on Jcorporate Ltd. and its products, please see
59  * <http://www.jcorporate.com/>.
60  *
61  * Portions of this software are based upon other open source
62  * products and are subject to their respective licenses.
63  */
64
65 /**
66  * Copyright 1999, 2000, 2001 Jcorporate Ltd.
67  */
68 package com.jcorporate.expresso.core.controller;
69
70 import com.jcorporate.expresso.core.cache.Cacheable;
71 import com.jcorporate.expresso.core.dbobj.ValidValue;
72 import com.jcorporate.expresso.core.misc.ConfigManager;
73 import com.jcorporate.expresso.core.misc.StringUtil;
74 import com.jcorporate.expresso.kernel.util.FastStringBuffer;
75 import org.w3c.dom.NamedNodeMap ;
76 import org.w3c.dom.Node ;
77 import org.w3c.dom.NodeList ;
78
79 import java.util.ArrayList ;
80 import java.util.Enumeration ;
81 import java.util.Iterator ;
82 import java.util.List ;
83 import java.util.Vector ;
84
85
86 /**
87  * An Input object is one of the three types of objects generated by a
88  * Controller when it transitions from one state to another. The other two
89  * are Actions and Outputs. <br>
90  * An Input is a request for information from the user. It may or may
91  * not have a default value, a list of valid values, and other
92  * attributes - any or all of which can be used by the user interface,
93  * which can be a JSP, Servlet, application, or even an applet.<br />
94  * <p/>
95  * <h4>Recognized Types:</h4>
96  * <p>The following types are recognized by the expresso framework and
97  * automatically rendered: You may add your own types or ignore them
98  * if you are doing your own page rendering.</p>
99  * <p/>
100  * <p>checkbox: Renders as a checkbox. If multivalued=true then will render
101  * the options as a list of checkboxes.</p>
102  * <p/>
103  * <p>radio: If multivalued, will render all options as a list of radio buttons
104  * </p>
105  * <p>checkbox-vertical: Only relevent for multivalues, renders the checkbox
106  * style as vertical</p>
107  */
108 public class Input
109         extends ControllerElement
110         implements Cloneable , Cacheable {
111
112     /**
113      * constant for JSTL attribute for 'selectness' of a given input
114      */
115     public static final String SELECTED = "selected";
116
117     /**
118      * Default value(s) for the item (optional)
119      */
120     private ArrayList defaultValue = null;
121
122     /**
123      * Vector of value/description pairs that are valid for this item
124      */
125     private Vector validValues = null;
126
127     /**
128      * Object name that can be used to look up valid values for
129      * this item
130      */
131     private String lookup = null;
132
133     /**
134      * Max length of the input field
135      */
136     private int maxLength = 80;
137
138     /** @todo add this variable for multi valued selects to work *RD* Mon Jul 27 2004 */
139     /**
140      * Multiple select true or false
141      */
142     private String multiple = "false";
143
144     /**
145      * Key used when this input is used as a Cacheable object
146      */
147     private String key = null;
148
149     /**
150      * The Following are known Input attributes
151      */
152
153     /**
154      * The Input is intended to be rendered as a List Box
155      */
156     public static final String ATTRIBUTE_LISTBOX = "listbox";
157
158     /**
159      * The Input is intended to be rendered as a drop down box
160      */
161     public static final String ATTRIBUTE_DROPDOWN = "dropdown";
162
163     /**
164      * The Input is intended to be rendered as a check box
165      */
166     public static final String ATTRIBUTE_CHECKBOX = "checkbox";
167
168     /**
169      * The Input is intended to be rendered as a vertically aligned checkbox
170      */
171     public static final String ATTRIBUTE_CHECKBOX_VERTICAL = "checkbox-vertical";
172
173     /**
174      * The Input is intended to be rendered as a Radio Button
175      */
176     public static final String ATTRIBUTE_RADIO = "radio";
177
178
179     /**
180      * The Input is intended to be rendered as a Vertically Aligned Radio Button
181      */
182     public static final String ATTRIBUTE_RADIO_VERTICAL = "radio-vertical";
183
184     /**
185      * The Input is intended to be rendered as a Text Area
186      */
187     public static final String ATTRIBUTE_TEXTAREA = "textarea";
188
189     /**
190      * The Input is intended to be rendered as a Hidden Field
191      */
192     public static final String ATTRIBUTE_HIDDEN = "hidden";
193
194
195     /**
196      * The Input is intended to be read only.
197      */
198     public static final String ATTRIBUTE_READONLY = "readOnly";
199
200
201     /**
202      * The Input is indended to be a file upload box.
203      */
204     public static final String ATTRIBUTE_FILE = "fileBox";
205
206
207     /**
208      * Attribute for password boxes.
209      */
210     public static final String ATTRIBUTE_PASSWORD = "password";
211
212     /**
213      * Attribute that contains the original value of this input. Usually set
214      * for read only inputs.
215      */
216     public static final String ATTRIBUTE_ORIGINAL_VALUE = "originalValue";
217
218     /**
219      * Defines the CSS style to use when rendering the input.
220      */
221     public static final String ATTRIBUTE_CSS_STYLE = "styleClass";
222
223     /**
224      * Means that the Input will be some sort of multi-valued field and
225      * has valid values associated with it.
226      */
227     public static final String ATTRIBUTE_MULTIVALUED = "multiValued";
228
229     /**
230      * text input, single line (as opposed to text area)
231      */
232     public static final String ATTRIBUTE_TEXTLINE = "text";
233
234
235     /**
236      * Attribute defines the HTML Type that will be used with the Input
237      */
238     public static final String ATTRIBUTE_TYPE = "type";
239
240
241     /**
242      * Default constructor
243      */
244     public Input() {
245         super();
246         setType(null);
247     } /* Input() */
248
249     /**
250      * Convenience constructor - to make a new Input object
251      * with a specific name
252      *
253      * @param newName the new input name
254      */
255     public Input(String newName) {
256         super();
257         setName(newName);
258         setType(null);
259     } /* Input(String) */
260
261
262     /**
263      * Constructor that sets the name and the label of the input
264      *
265      * @param newName the name of the Input
266      * @param newLabel the label of the input
267      */
268     public Input(String newName, String newLabel) {
269         super();
270         setName(newName);
271         setLabel(newLabel);
272         setType(null);
273     }
274
275     /**
276      * Clones the input as per standard java.lang.Object specifications
277      *
278      * @return java.lang.Object which is actually an Input.
279      */
280     public Object clone()
281             throws CloneNotSupportedException {
282         Input i;
283
284         synchronized (this) { // this sync means nothing since setter methods are not sync'd, but inputs are generally not handled by more than one thread at a time
285 i = (Input) super.clone();
286             if (defaultValue != null) {
287                 i.defaultValue = (ArrayList ) defaultValue.clone();
288             }
289             i.maxLength = maxLength;
290             i.lookup = (lookup);
291             i.key = key;
292             if (validValues != null) {
293                 i.validValues = (Vector ) validValues.clone();
294             }
295             if (getAttributes().size() > 0) {
296                 i.getAttributes().putAll(getAttributes());
297             }
298         }
299
300         return i;
301     }
302
303
304     /**
305      * Return a single default value supplied by the Controller for this
306      * Input object; returns the 0th item in list (we expect this function
307      * to be used only for single selection items)
308      *
309      * @return A String to be used as the default value for this Input; empty string if no default has been set
310      * @see #getDefaultValueList for multiple selections
311      */
312     public String getDefaultValue() {
313         String result = "";
314         if (defaultValue != null) {
315             result = (String ) defaultValue.get(0);
316         }
317
318         return result;
319     } /* getDefaultValue() */
320
321     /**
322      * (Convenience for JSTL access, to be parallel with Output)
323      * Return a single default value supplied by the Controller for this
324      * Input object; returns the 0th item in list (we expect this function
325      * to be used only for single selection items)
326      *
327      * @return A String to be used as the default value for this Input; empty string if no default has been set
328      * @see #getDefaultValueList for multiple selections
329      */
330     public String getContent() {
331         return getDefaultValue();
332     }
333
334     /**
335      * Return a list of default values supplied by the Controller for this
336      * Input object; appropriate for multiple selection items
337      *
338      * @return A list of strings to be used as the default values for this Input; never null, though list can be empty
339      * @see #getDefaultValue for single selections
340      */
341     public ArrayList getDefaultValueList() {
342         if (defaultValue == null) {
343             defaultValue = new ArrayList ();
344         }
345
346         return (ArrayList ) defaultValue.clone();
347     }
348
349     /**
350      * Returns the class name of a database object that can be used to
351      * look up valid values for this Input item, if there is one.
352      *
353      * @return java.lang.String the class name of the lookup database object
354      */
355     public String getLookup() {
356         return lookup;
357     } /* getLookup() */
358
359     /**
360      * Return the maximum recommended length of the value for this
361      * Input object.
362      *
363      * @return The maximum number of characters that should be supplied
364      * * as a value to this Input object
365      */
366     public int getMaxLength() {
367         return maxLength;
368     } /* getMaxLength() */
369
370     /**
371      * Concert the object to an xml fragment.
372      *
373      * @param stream A FastStringBuffer to append the data to.
374      * @return FastStringBuffer( usually the same one passed in)
375      * @todo adapt to support multiple default values
376      */
377     public FastStringBuffer toXML(FastStringBuffer stream) {
378         Vector vv = this.getValidValues();
379
380         if (vv == null) {
381             vv = new Vector ();
382         }
383
384         stream.append("<input");
385
386         if (this.getName() != null && this.getName().length() > 0) {
387             stream.append(" name=\"" + StringUtil.xmlEscape(this.getName()) +
388                     "\"");
389         }
390         if (vv.size() > 0) {
391             stream.append(" multivalue=\"y\"");
392         }
393         if (defaultValue != null && defaultValue.size() > 0) {
394             stream.append(" default-value=\"" +
395                     StringUtil.xmlEscape(this.getDefaultValue()) + "\"");
396         }
397         if (this.getMaxLength() > 0) {
398             stream.append(" max-length=\"" + this.getMaxLength() + "\"");
399         }
400         if (!StringUtil.notNull(this.getLookup()).equals("")) {
401             stream.append(" lookup-object=\"" +
402                     StringUtil.xmlEscape(this.getLookup()) + "\"");
403         }
404         if (this.getType() != null && this.getType().length() > 0) {
405             stream.append(" type=\"" + StringUtil.xmlEscape(this.getType()) +
406                     "\"");
407         }
408
409         stream.append(">\n");
410
411         if (vv.size() > 0) {
412             ValidValue oneValue = null;
413             stream.append(" <valid-values>\n");
414
415             for (Enumeration e = vv.elements(); e.hasMoreElements();) {
416                 oneValue = (ValidValue) e.nextElement();
417                 stream.append(" <valid-value value=\"" +
418                         StringUtil.xmlEscape(oneValue.getValue()) +
419                         "\" description=\"" +
420                         StringUtil.xmlEscape(oneValue.getDescription()) +
421                         "\" />\n");
422             }
423
424             stream.append(" </valid-values>\n");
425         }
426
427         //Super deals with nested ControllerElements
428 super.toXML(stream);
429         stream.append("</input>\n");
430
431         return stream;
432     }
433
434     /**
435      * Return a controller element based upon the xml fragment [Factory Method]
436      *
437      * @param n A DOM node to assemble this Input from.
438      * @return a constructed ControllerElement [Really an Input]
439      * @throws ControllerException if there was a parsing error. (ie malformed
440      * nodes)
441      * @throws ControllerException upon error
442      */
443     public static ControllerElement fromXML(Node n)
444             throws ControllerException {
445
446         //If we're at the root node, then it'll be doc instead of input.
447 if (n.getNodeName().equals("#document")) {
448             return fromXML(n.getChildNodes().item(0));
449         }
450         if (!n.getNodeName().equals("input")) {
451             throw new ControllerException("Failed To Get DOM Node of " +
452                     " type 'input' Got " +
453                     n.getNodeName() + " instead.");
454         }
455
456         Input i = new Input();
457         NamedNodeMap attributes = n.getAttributes();
458         Node oneAttribute = attributes.getNamedItem("name");
459
460         if (oneAttribute != null) {
461             i.setName(oneAttribute.getNodeValue());
462         }
463
464         oneAttribute = attributes.getNamedItem("default-value");
465
466         if (oneAttribute != null) {
467             i.setDefaultValue(oneAttribute.getNodeValue());
468         }
469
470         oneAttribute = attributes.getNamedItem("max-length");
471
472         if (oneAttribute != null) {
473             try {
474                 i.maxLength = Integer.parseInt(oneAttribute.getNodeValue());
475             } catch (NumberFormatException nfe) {
476             }
477         }
478
479         oneAttribute = attributes.getNamedItem("lookup-object");
480
481         if (oneAttribute != null) {
482             i.lookup = oneAttribute.getNodeValue();
483         }
484
485         oneAttribute = attributes.getNamedItem("type");
486
487         if (oneAttribute != null) {
488             i.setType(oneAttribute.getNodeValue());
489         }
490
491         NodeList children = n.getChildNodes();
492
493         for (int index = 0; index < children.getLength(); index++) {
494             Node oneChild = children.item(index);
495             String nodeName = oneChild.getNodeName();
496
497             if (nodeName != null) {
498                 if (nodeName.equals("valid-values")) {
499                     NodeList vv = oneChild.getChildNodes();
500
501                     for (int j = 0; j < vv.getLength(); j++) {
502                         Node onevalue = vv.item(j);
503
504                         if (onevalue.getNodeName().equals("valid-value")) {
505                             NamedNodeMap valueAttributes = onevalue.getAttributes();
506
507                             if (valueAttributes != null) {
508                                 String value;
509                                 String description;
510                                 Node attribute = valueAttributes.getNamedItem("value");
511
512                                 if (attribute != null) {
513                                     value = StringUtil.notNull(attribute.getNodeValue());
514                                     attribute = valueAttributes.getNamedItem("description");
515
516                                     if (attribute == null) {
517                                         description = ("");
518                                     } else {
519                                         description = attribute.getNodeValue();
520                                     }
521
522                                     i.addValidValue(value, description);
523                                 }
524                             }
525                         }
526                     }
527                 } else if (nodeName.equals("controller-element")) {
528                     i = (Input) ControllerElement.fromXML(oneChild, i);
529                 }
530             }
531         }
532
533         return i;
534     }
535
536     /**
537      * Return the list of Valid Values that are allowed for this
538      * Input item.
539      *
540      * @return A Vector of value/description pairs that enumerate
541      * * the valid values for this Input item. The user is expected
542      * * to select one of these values, but the presentation of the
543      * * list is up to the client (e.g. could be a drop-down, radio
544      * * buttons, etc). Can be empty, but Never null.
545      */
546     public Vector getValidValues() {
547         if (validValues == null) {
548             return new Vector ();
549         }
550         return validValues;
551     }
552
553     /**
554      * supply a default value for this
555      * Input object; appropriate for single selection items; sets the 0th item in underlying list
556      *
557      * @param newValue The new default value for this Input item
558      * @see #addDefaultValue for multiple selection
559      */
560     public void setDefaultValue(String newValue) {
561         if (newValue == null) {
562             // is this trying to unset a value?
563 if (defaultValue != null) {
564                 defaultValue.clear();
565             }
566
567             return;
568         }
569
570         if (defaultValue == null) {
571             defaultValue = new ArrayList ();
572         }
573
574         if (defaultValue.size() == 0) {
575             defaultValue.add(newValue);
576         } else {
577             defaultValue.set(0, newValue);
578         }
579     }
580
581     /**
582      * supply a list of default values for this
583      * Input object; appropriate for multiple selection items
584      *
585      * @param list The new list of default values (strings) for this Input item
586      * @see #addDefaultValue for adding multiple selection defaults one at a time
587      */
588     public void setDefaultValue(List list) {
589         if (list == null) {
590             // is this trying to unset a value?
591 if (defaultValue != null) {
592                 defaultValue.clear();
593             }
594
595             return;
596         }
597
598         if (defaultValue == null) {
599             defaultValue = new ArrayList (list);
600         } else {
601             defaultValue.clear();
602             defaultValue.addAll(list);
603         }
604     }
605
606     /**
607      * supply another default value for this
608      * Input object; appropriate for multiple selection items
609      *
610      * @param newValue The new default value for this Input item
611      * @see #setDefaultValue(String) for single selection
612      */
613     public void addDefaultValue(String newValue) {
614         if (newValue == null) {
615             return; // could throw, but seems nicer to just discard
616 }
617
618         if (defaultValue == null) {
619             defaultValue = new ArrayList ();
620         }
621
622         defaultValue.add(newValue);
623     }
624
625     /**
626      * Convenience method to quickly set the default value from the form cache.
627      *
628      * @param response The controller response where the form cache may exist
629      * @throws ControllerException upon error
630      */
631     public void setDefaultValue(ControllerResponse response)
632             throws ControllerException {
633         setDefaultValue(response.getFormCache(this.getName()));
634     }
635
636     /**
637      * Set the name of the "lookup object" - the database object that
638      * the client can use to look up valid values for this
639      * Input item.
640      *
641      * @param s the lookup class name to associate with the Input
642      */
643     public void setLookup(String s) {
644         lookup = s;
645     } /* setLookup(String) */
646
647     /**
648      * Set the maximum recommended length of the Input object
649      *
650      * @param newMaxLength Specify the max length (in chars) for this
651      * * input item's value.
652      */
653     public void setMaxLength(int newMaxLength) {
654         maxLength = newMaxLength;
655     } /* setMaxLength(int) */
656
657     /**
658      * Sets the inputs name. Also checks against reserved words
659      *
660      * @param newName the new name for the Input
661      * @throws IllegalArgumentException if the name is a 'reserved word' as
662      * defined by ConfigManager.
663      */
664     public void setName(String newName) {
665         if (ConfigManager.isParameterReservedWord(newName)) {
666             throw new IllegalArgumentException ("You cannot have a input name of " + newName +
667                     ". It is a reserved word. Check " +
668                     "com.jcorporate.expresso.core.misc.ConfigManager for a full list" +
669                     " of reservered words");
670         }
671
672         super.setName(newName);
673     }
674
675     /**
676      * Add a valid value to the Input's dropdown
677      *
678      * @param value the 'key' part of the valid value
679      * @param descrip the description part of the valid value.
680      */
681     public synchronized void addValidValue(String value, String descrip) {
682         ValidValue v = new ValidValue(value, descrip);
683
684         if (validValues == null) {
685             validValues = new Vector ();
686         }
687
688         validValues.addElement(v);
689     }
690
691     /**
692      * Sets the input type
693      *
694      * @param newType the new type as appears in an Input tag
695      */
696     public void setType(String newType) {
697         if (newType == null) {
698             super.setType("C");
699         } else {
700             super.setType(newType);
701         }
702     }
703
704     /**
705      * Method for the Controller to specify the valid values for this
706      * Input item
707      *
708      * @param v The value/description pairs that make up the
709      * * valid values for this Input object.
710      */
711     public void setValidValues(Vector v) {
712         validValues = v;
713     } /* setValidValues(Vector) */
714
715     /**
716      * The Key of the Input
717      *
718      * @param newKey the new value
719      */
720     public synchronized void setKey(String newKey) {
721         key = newKey;
722     } /* setKey(String) */
723
724     /**
725      * Retrieve the key for the input.
726      *
727      * @return java.lang.String
728      */
729     public String getKey() {
730         return key;
731     } /* getKey() */
732
733     /** @todo add this two methods for multi-valued fields to work *RD* Mon Jul 27 2004 */
734     /**
735      * Set the the Input object allow multiple selections
736      *
737      * @param newMultiple Specify if true or false the input will accept multiple selects.
738      */
739     public void setMultiple(String newMultiple) {
740         multiple = newMultiple;
741     } /* setMultiple(String) */
742
743     /**
744      * Retrieve the multi select status.
745      *
746      * @return java.lang.String
747      */
748     public String getMultiple() {
749         return multiple;
750     } /* getMultiple() */
751
752     /**
753      * get the display string associated with the currently-selected (default).
754      * useful for a JSTL reuse of Input for output purposes, when
755      * the default value is an ID, while its partner ValidValue pairing is the display string.
756      *
757      * @return the display string associated with the currently-selected (default) value, or empty string if none found--never null
758      */
759     public String getSelectedDisplay() {
760         String result = "";
761         String currentIndex = getDefaultValue();
762         if (currentIndex != null && validValues != null) {
763             for (Iterator iterator = validValues.iterator(); iterator.hasNext();) {
764                 ValidValue vv = (ValidValue) iterator.next();
765                 if (currentIndex.equals(vv.getValue())) {
766                     result = vv.getDescription();
767                     break;
768                 }
769             }
770         }
771
772         if (result == null) {
773             result = "";
774         }
775         return result;
776     }
777 } /* Input */
778

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags