1 package org.apache.turbine.util.parser;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import javax.servlet.http.HttpServletRequest;
23
24 import org.apache.commons.fileupload.FileItem;
25
26 /***
27 * ParameterParser is an interface to a utility to handle parsing and
28 * retrieving the data passed via the GET/POST/PATH_INFO arguments.
29 *
30 * <p>NOTE: The name= portion of a name=value pair may be converted
31 * to lowercase or uppercase when the object is initialized and when
32 * new data is added. This behaviour is determined by the url.case.folding
33 * property in TurbineResources.properties. Adding a name/value pair may
34 * overwrite existing name=value pairs if the names match:
35 *
36 * <pre>
37 * ParameterParser pp = data.getParameters();
38 * pp.add("ERROR",1);
39 * pp.add("eRrOr",2);
40 * int result = pp.getInt("ERROR");
41 * </pre>
42 *
43 * In the above example, result is 2.
44 *
45 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
46 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
47 * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
48 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
49 * @version $Id: ParameterParser.java 534527 2007-05-02 16:10:59Z tv $
50 */
51 public interface ParameterParser
52 extends ValueParser
53 {
54 /***
55 * Gets the parsed servlet request.
56 *
57 * @return the parsed servlet request or null.
58 */
59 HttpServletRequest getRequest();
60
61 /***
62 * Sets the servlet request to be parser. This requires a
63 * valid HttpServletRequest object. It will attempt to parse out
64 * the GET/POST/PATH_INFO data and store the data into a Map.
65 * There are convenience methods for retrieving the data as a
66 * number of different datatypes. The PATH_INFO data must be a
67 * URLEncoded() string.
68 *
69 * <p>To add name/value pairs to this set of parameters, use the
70 * <code>add()</code> methods.
71 *
72 * @param req An HttpServletRequest.
73 */
74 void setRequest(HttpServletRequest req);
75
76 /***
77 * Sets the uploadData byte[]
78 *
79 * @param uploadData A byte[] with data.
80 */
81 void setUploadData(byte[] uploadData);
82
83 /***
84 * Gets the uploadData byte[]
85 *
86 * @return uploadData A byte[] with data.
87 */
88 byte[] getUploadData();
89
90 /***
91 * Add a FileItem object as a parameters. If there are any
92 * FileItems already associated with the name, append to the
93 * array. The reason for this is that RFC 1867 allows multiple
94 * files to be associated with single HTML input element.
95 *
96 * @param name A String with the name.
97 * @param item A FileItem with the value.
98 *
99 * @deprecated Use add(String name, FileItem item) instead.
100 */
101 void append(String name, FileItem item);
102
103 /***
104 * Add a FileItem object as a parameters. If there are any
105 * FileItems already associated with the name, append to the
106 * array. The reason for this is that RFC 1867 allows multiple
107 * files to be associated with single HTML input element.
108 *
109 * @param name A String with the name.
110 * @param item A FileItem with the value.
111 */
112 void add(String name, FileItem item);
113
114 /***
115 * Return a FileItem object for the given name. If the name does
116 * not exist or the object stored is not a FileItem, return null.
117 *
118 * @param name A String with the name.
119 * @return A FileItem.
120 */
121 FileItem getFileItem(String name);
122
123 /***
124 * Return an array of FileItem objects for the given name. If the
125 * name does not exist or the object stored is not a FileItem
126 * array, return null.
127 *
128 * @param name A String with the name.
129 * @return A FileItem[].
130 */
131 FileItem[] getFileItems(String name);
132 }