    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.fileupload2.jakarta.servlet5;
    018
    019import java.io.IOException;
    020import java.util.List;
    021import java.util.Map;
    022
    023import org.apache.commons.fileupload2.core.AbstractFileUpload;
    024import org.apache.commons.fileupload2.core.FileItem;
    025import org.apache.commons.fileupload2.core.FileItemFactory;
    026import org.apache.commons.fileupload2.core.FileItemInputIterator;
    027import org.apache.commons.fileupload2.core.FileUploadException;
    028
    029import jakarta.servlet.http.HttpServletRequest;
    030
    031/**
    032 * High level API for processing file uploads.
    033 * <p>
    034 * This class handles multiple files per single HTML widget, sent using {@code multipart/mixed} encoding type, as specified by
    035 * <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>. Use {@link #parseRequest(HttpServletRequest)} to acquire a list of {@link FileItem}s associated
    036 * with a given HTML widget.
    037 * </p>
    038 * <p>
    039 * How the data for individual parts is stored is determined by the factory used to create them; a given part may be in memory, on disk, or somewhere else.
    040 * </p>
    041 *
    042 * @param <I> The FileItem type.
    043 * @param <F> the FileItemFactory type.
    044 */
    045public class JakartaServletFileUpload<I extends FileItem<I>, F extends FileItemFactory<I>> extends AbstractFileUpload<HttpServletRequest, I, F> {
    046
    047    /**
    048     * Constant for HTTP POST method.
    049     */
    050    private static final String POST_METHOD = "POST";
    051
    052    /**
    053     * Tests whether the request contains multipart content.
    054     *
    055     * @param request The servlet request to be evaluated. Must be non-null.
    056     *
    057     * @return {@code true} if the request is multipart; {@code false} otherwise.
    058     */
    059    public static final boolean isMultipartContent(final HttpServletRequest request) {
    060        return POST_METHOD.equalsIgnoreCase(request.getMethod()) && AbstractFileUpload.isMultipartContent(new JakartaServletRequestContext(request));
    061    }
    062
    063    /**
    064     * Constructs an uninitialized instance of this class. A factory must be configured, using {@code setFileItemFactory()}, before attempting to parse
    065     * requests.
    066     *
    067     * @see AbstractFileUpload#AbstractFileUpload()
    068     */
    069    public JakartaServletFileUpload() {
    070    }
    071
    072    /**
    073     * Constructs an instance of this class which uses the supplied factory to create {@code FileItem} instances.
    074     *
    075     * @see AbstractFileUpload#AbstractFileUpload()
    076     * @param fileItemFactory The factory to use for creating file items.
    077     */
    078    public JakartaServletFileUpload(final F fileItemFactory) {
    079        setFileItemFactory(fileItemFactory);
    080    }
    081
    082    /**
    083     * Gets an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant {@code multipart/form-data} file item iterator.
    084     *
    085     * @param request The servlet request to be parsed.
    086     * @return An iterator to instances of {@code FileItemInput} parsed from the request, in the order that they were transmitted.
    087     * @throws FileUploadException if there are problems reading/parsing the request or storing files.
    088     * @throws IOException         An I/O error occurred. This may be a network error while communicating with the client or a problem while storing the
    089     *                             uploaded content.
    090     */
    091    @Override
    092    public FileItemInputIterator getItemIterator(final HttpServletRequest request) throws FileUploadException, IOException {
    093        return super.getItemIterator(new JakartaServletRequestContext(request));
    094    }
    095
    096    /**
    097     * Parses an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant {@code multipart/form-data} stream.
    098     *
    099     * @param request The servlet request to be parsed.
    100     * @return A map of {@code FileItem} instances parsed from the request.
    101     * @throws FileUploadException if there are problems reading/parsing the request or storing files.
    102     */
    103    @Override
    104    public Map<String, List<I>> parseParameterMap(final HttpServletRequest request) throws FileUploadException {
    105        return parseParameterMap(new JakartaServletRequestContext(request));
    106    }
    107
    108    /**
    109     * Parses an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant {@code multipart/form-data} stream.
    110     *
    111     * @param request The servlet request to be parsed.
    112     * @return A list of {@code FileItem} instances parsed from the request, in the order that they were transmitted.
    113     * @throws FileUploadException if there are problems reading/parsing the request or storing files.
    114     */
    115    @Override
    116    public List<I> parseRequest(final HttpServletRequest request) throws FileUploadException {
    117        return parseRequest(new JakartaServletRequestContext(request));
    118    }
    119
    120}