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