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.portlet;
    18
    19  import java.io.IOException;
    20  import java.util.List;
    21  import java.util.Map;
    22
    23  import javax.portlet.ActionRequest;
    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
    38   * {@link org.apache.commons.fileupload.servlet.ServletFileUpload
    39   * #parseRequest(javax.servlet.http.HttpServletRequest)} to acquire a list
    40   * of {@link org.apache.commons.fileupload.FileItem FileItems} associated
    41   * with a given HTML widget.</p>
    42   *
    43   * <p>How the data for individual parts is stored is determined by the factory
    44   * used to create them; a given part may be in memory, on disk, or somewhere
    45   * else.</p>
    46   *
    47   * @since FileUpload 1.1
    48   */
    49  public class PortletFileUpload extends FileUpload {
    50
    51      /**
    52       * Utility method that determines whether the request contains multipart
    53       * content.
    54       *
    55       * @param request The portlet request to be evaluated. Must be non-null.
    56       * @return {@code true} if the request is multipart;
    57       *         {@code false} otherwise.
    58       */
    59      public static final boolean isMultipartContent(final ActionRequest request) {
    60          return FileUploadBase.isMultipartContent(
    61                  new PortletRequestContext(request));
    62      }
    63
    64      /**
    65       * Constructs an uninitialized instance of this class. A factory must be
    66       * configured, using {@code setFileItemFactory()}, before attempting
    67       * to parse requests.
    68       *
    69       * @see FileUpload#FileUpload(FileItemFactory)
    70       */
    71      public PortletFileUpload() {
    72      }
    73
    74      /**
    75       * Constructs an instance of this class which uses the supplied factory to
    76       * create {@code FileItem} instances.
    77       *
    78       * @see FileUpload#FileUpload()
    79       * @param fileItemFactory The factory to use for creating file items.
    80       */
    81      public PortletFileUpload(final FileItemFactory fileItemFactory) {
    82          super(fileItemFactory);
    83      }
    84
    85      /**
    86       * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    87       * compliant {@code multipart/form-data} stream.
    88       *
    89       * @param request The portlet request to be parsed.
    90       * @return An iterator to instances of {@code FileItemStream}
    91       *         parsed from the request, in the order that they were
    92       *         transmitted.
    93       *
    94       * @throws FileUploadException if there are problems reading/parsing
    95       *                             the request or storing files.
    96       * @throws IOException An I/O error occurred. This may be a network
    97       *   error while communicating with the client or a problem while
    98       *   storing the uploaded content.
    99       */
    100     public FileItemIterator getItemIterator(final ActionRequest request)
    101             throws FileUploadException, IOException {
    102         return super.getItemIterator(new PortletRequestContext(request));
    103     }
    104
    105     /**
    106      * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    107      * compliant {@code multipart/form-data} stream.
    108      *
    109      * @param request The portlet request to be parsed.
    110      * @return A map of {@code FileItem} instances parsed from the request.
    111      * @throws FileUploadException if there are problems reading/parsing
    112      *                             the request or storing files.
    113      *
    114      * @since 1.3
    115      */
    116     public Map<String, List<FileItem>> parseParameterMap(final ActionRequest request)
    117             throws FileUploadException {
    118         return parseParameterMap(new PortletRequestContext(request));
    119     }
    120
    121     /**
    122      * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
    123      * compliant {@code multipart/form-data} stream.
    124      *
    125      * @param request The portlet request to be parsed.
    126      * @return A list of {@code FileItem} instances parsed from the
    127      *         request, in the order that they were transmitted.
    128      *
    129      * @throws FileUploadException if there are problems reading/parsing
    130      *                             the request or storing files.
    131      */
    132     public List<FileItem> parseRequest(final ActionRequest request)
    133             throws FileUploadException {
    134         return parseRequest(new PortletRequestContext(request));
    135     }
    136
    137 }