001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.fileupload.servlet;
018
019import java.io.IOException;
020import java.util.List;
021import java.util.Map;
022
023import javax.servlet.http.HttpServletRequest;
024
025import org.apache.commons.fileupload.FileItem;
026import org.apache.commons.fileupload.FileItemFactory;
027import org.apache.commons.fileupload.FileItemIterator;
028import org.apache.commons.fileupload.FileUpload;
029import org.apache.commons.fileupload.FileUploadBase;
030import org.apache.commons.fileupload.FileUploadException;
031
032/**
033 * <p>High level API for processing file uploads.</p>
034 *
035 * <p>This class handles multiple files per single HTML widget, sent using
036 * <code>multipart/mixed</code> encoding type, as specified by
037 * <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.  Use {@link
038 * #parseRequest(HttpServletRequest)} to acquire a list of {@link
039 * org.apache.commons.fileupload.FileItem}s associated with a given HTML
040 * widget.</p>
041 *
042 * <p>How the data for individual parts is stored is determined by the factory
043 * used to create them; a given part may be in memory, on disk, or somewhere
044 * else.</p>
045 *
046 * @version $Id: ServletFileUpload.java 1455949 2013-03-13 14:14:44Z simonetripodi $
047 */
048public class ServletFileUpload extends FileUpload {
049
050    /**
051     * Constant for HTTP POST method.
052     */
053    private static final String POST_METHOD = "POST";
054
055    // ---------------------------------------------------------- Class methods
056
057    /**
058     * Utility method that determines whether the request contains multipart
059     * content.
060     *
061     * @param request The servlet request to be evaluated. Must be non-null.
062     *
063     * @return <code>true</code> if the request is multipart;
064     *         <code>false</code> otherwise.
065     */
066    public static final boolean isMultipartContent(
067            HttpServletRequest request) {
068        if (!POST_METHOD.equalsIgnoreCase(request.getMethod())) {
069            return false;
070        }
071        return FileUploadBase.isMultipartContent(new ServletRequestContext(request));
072    }
073
074    // ----------------------------------------------------------- Constructors
075
076    /**
077     * Constructs an uninitialised instance of this class. A factory must be
078     * configured, using <code>setFileItemFactory()</code>, before attempting
079     * to parse requests.
080     *
081     * @see FileUpload#FileUpload(FileItemFactory)
082     */
083    public ServletFileUpload() {
084        super();
085    }
086
087    /**
088     * Constructs an instance of this class which uses the supplied factory to
089     * create <code>FileItem</code> instances.
090     *
091     * @see FileUpload#FileUpload()
092     * @param fileItemFactory The factory to use for creating file items.
093     */
094    public ServletFileUpload(FileItemFactory fileItemFactory) {
095        super(fileItemFactory);
096    }
097
098    // --------------------------------------------------------- Public methods
099
100    /**
101     * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
102     * compliant <code>multipart/form-data</code> stream.
103     *
104     * @param request The servlet request to be parsed.
105     *
106     * @return A list of <code>FileItem</code> instances parsed from the
107     *         request, in the order that they were transmitted.
108     *
109     * @throws FileUploadException if there are problems reading/parsing
110     *                             the request or storing files.
111     */
112    @Override
113    public List<FileItem> parseRequest(HttpServletRequest request)
114    throws FileUploadException {
115        return parseRequest(new ServletRequestContext(request));
116    }
117
118    /**
119     * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
120     * compliant <code>multipart/form-data</code> stream.
121     *
122     * @param request The servlet request to be parsed.
123     *
124     * @return A map of <code>FileItem</code> instances parsed from the request.
125     *
126     * @throws FileUploadException if there are problems reading/parsing
127     *                             the request or storing files.
128     *
129     * @since 1.3
130     */
131    public Map<String, List<FileItem>> parseParameterMap(HttpServletRequest request)
132            throws FileUploadException {
133        return parseParameterMap(new ServletRequestContext(request));
134    }
135
136    /**
137     * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
138     * compliant <code>multipart/form-data</code> stream.
139     *
140     * @param request The servlet request to be parsed.
141     *
142     * @return An iterator to instances of <code>FileItemStream</code>
143     *         parsed from the request, in the order that they were
144     *         transmitted.
145     *
146     * @throws FileUploadException if there are problems reading/parsing
147     *                             the request or storing files.
148     * @throws IOException An I/O error occurred. This may be a network
149     *   error while communicating with the client or a problem while
150     *   storing the uploaded content.
151     */
152    public FileItemIterator getItemIterator(HttpServletRequest request)
153    throws FileUploadException, IOException {
154        return super.getItemIterator(new ServletRequestContext(request));
155    }
156
157}