001 package org.apache.fulcrum.parser;
002
003
004 /*
005 * Licensed to the Apache Software Foundation (ASF) under one
006 * or more contributor license agreements. See the NOTICE file
007 * distributed with this work for additional information
008 * regarding copyright ownership. The ASF licenses this file
009 * to you under the Apache License, Version 2.0 (the
010 * "License"); you may not use this file except in compliance
011 * with the License. You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing,
016 * software distributed under the License is distributed on an
017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018 * KIND, either express or implied. See the License for the
019 * specific language governing permissions and limitations
020 * under the License.
021 */
022
023
024 import javax.servlet.http.HttpServletRequest;
025
026 import org.apache.commons.fileupload.FileItem;
027
028 /**
029 * ParameterParser is an interface to a utility to handle parsing and
030 * retrieving the data passed via the GET/POST/PATH_INFO arguments.
031 *
032 * <p>NOTE: The name= portion of a name=value pair may be converted
033 * to lowercase or uppercase when the object is initialized and when
034 * new data is added. This behaviour is determined by the url.case.folding
035 * property in TurbineResources.properties. Adding a name/value pair may
036 * overwrite existing name=value pairs if the names match:
037 *
038 * <pre>
039 * ParameterParser pp = data.getParameters();
040 * pp.add("ERROR",1);
041 * pp.add("eRrOr",2);
042 * int result = pp.getInt("ERROR");
043 * </pre>
044 *
045 * In the above example, result is 2.
046 *
047 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
048 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
049 * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
050 * @author <a href="mailto:jh@byteaction.de">Jürgen Hoffmann</a>
051 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
052 * @version $Id: ParameterParser.java 812786 2009-09-09 07:01:49Z tv $
053 */
054 public interface ParameterParser
055 extends ValueParser
056 {
057 /**
058 * Gets the parsed servlet request.
059 *
060 * @return the parsed servlet request or null.
061 */
062 HttpServletRequest getRequest();
063
064 /**
065 * Sets the servlet request to be parser. This requires a
066 * valid HttpServletRequest object. It will attempt to parse out
067 * the GET/POST/PATH_INFO data and store the data into a Hashtable.
068 * There are convenience methods for retrieving the data as a
069 * number of different datatypes. The PATH_INFO data must be a
070 * URLEncoded() string.
071 *
072 * <p>To add name/value pairs to this set of parameters, use the
073 * <code>add()</code> methods.
074 *
075 * @param req An HttpServletRequest.
076 */
077 void setRequest(HttpServletRequest req);
078
079 /**
080 * Sets the uploadData byte[]
081 *
082 * @param uploadData A byte[] with data.
083 */
084 void setUploadData ( byte[] uploadData );
085
086 /**
087 * Gets the uploadData byte[]
088 *
089 * @return uploadData A byte[] with data.
090 */
091 byte[] getUploadData ();
092
093
094 /**
095 * Add a FileItem object as a parameters. If there are any
096 * FileItems already associated with the name, append to the
097 * array. The reason for this is that RFC 1867 allows multiple
098 * files to be associated with single HTML input element.
099 *
100 * @param name A String with the name.
101 * @param value A FileItem with the value.
102 */
103 void append( String name, FileItem value );
104
105
106 /**
107 * Return a FileItem object for the given name. If the name does
108 * not exist or the object stored is not a FileItem, return null.
109 *
110 * @param name A String with the name.
111 * @return A FileItem.
112 */
113 FileItem getFileItem(String name);
114
115 /**
116 * Return an array of FileItem objects for the given name. If the
117 * name does not exist or the object stored is not a FileItem
118 * array, return null.
119 *
120 * @param name A String with the name.
121 * @return A FileItem[].
122 */
123 FileItem[] getFileItems(String name);
124 }