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