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&#252;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    }