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 *      https://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.servlet6;
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="https://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     * Tests whether the request contains multipart content.
049     *
050     * @param request The servlet request to be evaluated. Must be non-null.
051     * @return {@code true} if the request is multipart; {@code false} otherwise.
052     */
053    public static final boolean isMultipartContent(final HttpServletRequest request) {
054        return isMultipartRequestMethod(request.getMethod()) && isMultipartContent(new JakartaServletRequestContext(request));
055    }
056
057    /**
058     * Constructs an uninitialized instance of this class. A factory must be configured, using {@code setFileItemFactory()}, before attempting to parse
059     * requests.
060     *
061     * @see AbstractFileUpload#AbstractFileUpload()
062     */
063    public JakartaServletFileUpload() {
064    }
065
066    /**
067     * Constructs an instance of this class which uses the supplied factory to create {@code FileItem} instances.
068     *
069     * @see AbstractFileUpload#AbstractFileUpload()
070     * @param fileItemFactory The factory to use for creating file items.
071     */
072    public JakartaServletFileUpload(final F fileItemFactory) {
073        setFileItemFactory(fileItemFactory);
074    }
075
076    /**
077     * Gets an <a href="https://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant {@code multipart/form-data} file item iterator.
078     *
079     * @param request The servlet request to be parsed.
080     * @return An iterator to instances of {@code FileItemInput} parsed from the request, in the order that they were transmitted.
081     * @throws FileUploadException if there are problems reading/parsing the request or storing files.
082     * @throws IOException         An I/O error occurred. This may be a network error while communicating with the client or a problem while storing the
083     *                             uploaded content.
084     */
085    @Override
086    public FileItemInputIterator getItemIterator(final HttpServletRequest request) throws FileUploadException, IOException {
087        return super.getItemIterator(new JakartaServletRequestContext(request));
088    }
089
090    /**
091     * Parses an <a href="https://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant {@code multipart/form-data} stream.
092     *
093     * @param request The servlet request to be parsed.
094     * @return A map of {@code FileItem} instances parsed from the request.
095     * @throws FileUploadException if there are problems reading/parsing the request or storing files.
096     */
097    @Override
098    public Map<String, List<I>> parseParameterMap(final HttpServletRequest request) throws FileUploadException {
099        return parseParameterMap(new JakartaServletRequestContext(request));
100    }
101
102    /**
103     * Parses an <a href="https://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant {@code multipart/form-data} stream.
104     *
105     * @param request The servlet request to be parsed.
106     * @return A list of {@code FileItem} instances parsed from the request, in the order that they were transmitted.
107     * @throws FileUploadException if there are problems reading/parsing the request or storing files.
108     */
109    @Override
110    public List<I> parseRequest(final HttpServletRequest request) throws FileUploadException {
111        return parseRequest(new JakartaServletRequestContext(request));
112    }
113
114}