001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry.multipart;
016    
017    import javax.servlet.http.HttpServletRequest;
018    
019    import org.apache.tapestry.request.IUploadFile;
020    
021    /**
022     * Defines how a multipart HTTP request can be broken into individual elements
023     * (including file uploads).
024     * <p>
025     * Multipart decoder implementations must be threadsafe.
026     * 
027     * @author Howard Lewis Ship
028     * @since 2.3
029     */
030    
031    public interface IMultipartDecoder
032    {
033    
034        /**
035         * Decodes the incoming request, identifying all the parts (values and
036         * uploaded files) contained within.
037         */
038    
039        void decode(HttpServletRequest request);
040    
041        /**
042         * Invoked to release any resources needed by tghe decoder. In some cases,
043         * large incoming parts are written to temporary files; this method ensures
044         * those temporary files are deleted.
045         */
046    
047        void cleanup(HttpServletRequest request);
048    
049        /**
050         * Returns the single value (or first value) for the parameter with the
051         * specified name. Returns null if no such parameter was in the request.
052         */
053    
054        String getString(HttpServletRequest request, String name);
055    
056        /**
057         * Returns an array of values (possibly a single element array). Returns
058         * null if no such parameter was in the request.
059         */
060    
061        String[] getStrings(HttpServletRequest request, String name);
062    
063        /**
064         * Returns the uploaded file with the specified parameter name, or null if
065         * no such parameter was in the request.
066         */
067    
068        IUploadFile getUploadFile(HttpServletRequest request, String name);
069    
070        /**
071         * Returns the names of all parameters whose type is string (not file
072         * upload).
073         * 
074         * @since 4.0
075         */
076        String[] getStringParameterNames(HttpServletRequest request);
077    }