View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.fileupload.servlet;
    18
    19  import java.io.IOException;
    20  import java.util.List;
    21  import java.util.Map;
    22
    23  import javax.servlet.http.HttpServletRequest;
    24
    25  import org.apache.commons.fileupload.FileItem;
    26  import org.apache.commons.fileupload.FileItemFactory;
    27  import org.apache.commons.fileupload.FileItemIterator;
    28  import org.apache.commons.fileupload.FileUpload;
    29  import org.apache.commons.fileupload.FileUploadBase;
    30  import org.apache.commons.fileupload.FileUploadException;
    31
    32  /**
    33   * <p>High level API for processing file uploads.</p>
    34   *
    35   * <p>This class handles multiple files per single HTML widget, sent using
    36   * {@code multipart/mixed} encoding type, as specified by
    37   * <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.  Use {@link
    38   * #parseRequest(HttpServletRequest)} to acquire a list of {@link
    39   * org.apache.commons.fileupload.FileItem}s associated with a given HTML
    40   * widget.</p>
    41   *
    42   * <p>How the data for individual parts is stored is determined by the factory
    43   * used to create them; a given part may be in memory, on disk, or somewhere
    44   * else.</p>
    45   */
    46  public class ServletFileUpload extends FileUpload {
    47
    48      /**
    49       * Constant for HTTP POST method.
    50       */
    51      private static final String POST_METHOD = "POST";
    52
    53      /**
    54       * Utility method that determines whether the request contains multipart
    55       * content.
    56       *
    57       * @param request The servlet request to be evaluated. Must be non-null.
    58       * @return {@code true} if the request is multipart;
    59       *         {@code false} otherwise.
    60       */
    61      public static final boolean isMultipartContent(
    62              final HttpServletRequest request) {
    63          if (!POST_METHOD.equalsIgnoreCase(request.getMethod())) {
    64              return false;
    65          }
    66          return FileUploadBase.isMultipartContent(new ServletRequestContext(request));
    67      }
    68
    69      /**
    70       * Constructs an uninitialized instance of this class. A factory must be
    71       * configured, using {@code setFileItemFactory()}, before attempting
    72       * to parse requests.
    73       *
    74       * @see FileUpload#FileUpload(FileItemFactory)
    75       */
    76      public ServletFileUpload() {
    77      }
    78
    79      /**
    80       * Constructs an instance of this class which uses the supplied factory to
    81       * create {@code FileItem} instances.
    82       *
    83       * @see FileUpload#FileUpload()
    84       * @param fileItemFactory The factory to use for creating file items.
    85       */
    86      public ServletFileUpload(final FileItemFactory fileItemFactory) {
    87          super(fileItemFactory);
    88      }
    89
    90      /**
    91       * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    92       * compliant {@code multipart/form-data} stream.
    93       *
    94       * @param request The servlet request to be parsed.
    95       * @return An iterator to instances of {@code FileItemStream}
    96       *         parsed from the request, in the order that they were
    97       *         transmitted.
    98       *
    99       * @throws FileUploadException if there are problems reading/parsing
    100      *                             the request or storing files.
    101      * @throws IOException An I/O error occurred. This may be a network
    102      *   error while communicating with the client or a problem while
    103      *   storing the uploaded content.
    104      */
    105     public FileItemIterator getItemIterator(final HttpServletRequest request)
    106     throws FileUploadException, IOException {
    107         return super.getItemIterator(new ServletRequestContext(request));
    108     }
    109
    110     /**
    111      * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    112      * compliant {@code multipart/form-data} stream.
    113      *
    114      * @param request The servlet request to be parsed.
    115      * @return A map of {@code FileItem} instances parsed from the request.
    116      * @throws FileUploadException if there are problems reading/parsing
    117      *                             the request or storing files.
    118      *
    119      * @since 1.3
    120      */
    121     public Map<String, List<FileItem>> parseParameterMap(final HttpServletRequest request)
    122             throws FileUploadException {
    123         return parseParameterMap(new ServletRequestContext(request));
    124     }
    125
    126     /**
    127      * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    128      * compliant {@code multipart/form-data} stream.
    129      *
    130      * @param request The servlet request to be parsed.
    131      * @return A list of {@code FileItem} instances parsed from the
    132      *         request, in the order that they were transmitted.
    133      *
    134      * @throws FileUploadException if there are problems reading/parsing
    135      *                             the request or storing files.
    136      */
    137     @Override
    138     public List<FileItem> parseRequest(final HttpServletRequest request)
    139     throws FileUploadException {
    140         return parseRequest(new ServletRequestContext(request));
    141     }
    142
    143 }