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</code> 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      // ---------------------------------------------------------- Class methods
    54
    55      /**
    56       * Utility method that determines whether the request contains multipart
    57       * content.
    58       *
    59       * @param request The servlet request to be evaluated. Must be non-null.
    60       *
    61       * @return <code>true</code> if the request is multipart;
    62       *         <code>false</code> otherwise.
    63       */
    64      public static final boolean isMultipartContent(
    65              HttpServletRequest request) {
    66          if (!POST_METHOD.equalsIgnoreCase(request.getMethod())) {
    67              return false;
    68          }
    69          return FileUploadBase.isMultipartContent(new ServletRequestContext(request));
    70      }
    71
    72      // ----------------------------------------------------------- Constructors
    73
    74      /**
    75       * Constructs an uninitialised instance of this class. A factory must be
    76       * configured, using <code>setFileItemFactory()</code>, before attempting
    77       * to parse requests.
    78       *
    79       * @see FileUpload#FileUpload(FileItemFactory)
    80       */
    81      public ServletFileUpload() {
    82          super();
    83      }
    84
    85      /**
    86       * Constructs an instance of this class which uses the supplied factory to
    87       * create <code>FileItem</code> instances.
    88       *
    89       * @see FileUpload#FileUpload()
    90       * @param fileItemFactory The factory to use for creating file items.
    91       */
    92      public ServletFileUpload(FileItemFactory fileItemFactory) {
    93          super(fileItemFactory);
    94      }
    95
    96      // --------------------------------------------------------- Public methods
    97
    98      /**
    99       * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    100      * compliant <code>multipart/form-data</code> stream.
    101      *
    102      * @param request The servlet request to be parsed.
    103      *
    104      * @return A list of <code>FileItem</code> instances parsed from the
    105      *         request, in the order that they were transmitted.
    106      *
    107      * @throws FileUploadException if there are problems reading/parsing
    108      *                             the request or storing files.
    109      */
    110     @Override
    111     public List<FileItem> parseRequest(HttpServletRequest request)
    112     throws FileUploadException {
    113         return parseRequest(new ServletRequestContext(request));
    114     }
    115
    116     /**
    117      * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    118      * compliant <code>multipart/form-data</code> stream.
    119      *
    120      * @param request The servlet request to be parsed.
    121      *
    122      * @return A map of <code>FileItem</code> instances parsed from the request.
    123      *
    124      * @throws FileUploadException if there are problems reading/parsing
    125      *                             the request or storing files.
    126      *
    127      * @since 1.3
    128      */
    129     public Map<String, List<FileItem>> parseParameterMap(HttpServletRequest request)
    130             throws FileUploadException {
    131         return parseParameterMap(new ServletRequestContext(request));
    132     }
    133
    134     /**
    135      * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    136      * compliant <code>multipart/form-data</code> stream.
    137      *
    138      * @param request The servlet request to be parsed.
    139      *
    140      * @return An iterator to instances of <code>FileItemStream</code>
    141      *         parsed from the request, in the order that they were
    142      *         transmitted.
    143      *
    144      * @throws FileUploadException if there are problems reading/parsing
    145      *                             the request or storing files.
    146      * @throws IOException An I/O error occurred. This may be a network
    147      *   error while communicating with the client or a problem while
    148      *   storing the uploaded content.
    149      */
    150     public FileItemIterator getItemIterator(HttpServletRequest request)
    151     throws FileUploadException, IOException {
    152         return super.getItemIterator(new ServletRequestContext(request));
    153     }
    154
    155 }