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,v 1.1.2.2 2004/05/20 03:33:43 seade Exp $
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 value A FileItem with the value.
95 */
96 void append(String name, FileItem value);
97
98 /***
99 * Return a FileItem object for the given name. If the name does
100 * not exist or the object stored is not a FileItem, return null.
101 *
102 * @param name A String with the name.
103 * @return A FileItem.
104 */
105 FileItem getFileItem(String name);
106
107 /***
108 * Return an array of FileItem objects for the given name. If the
109 * name does not exist or the object stored is not a FileItem
110 * array, return null.
111 *
112 * @param name A String with the name.
113 * @return A FileItem[].
114 */
115 FileItem[] getFileItems(String name);
116 }