View Javadoc

1   package org.apache.turbine.util.parser;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
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 }