View Javadoc

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