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