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 *      http://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.fileupload.portlet;
018
019import java.io.IOException;
020import java.util.List;
021import java.util.Map;
022
023import javax.portlet.ActionRequest;
024
025import org.apache.commons.fileupload.FileItem;
026import org.apache.commons.fileupload.FileItemFactory;
027import org.apache.commons.fileupload.FileItemIterator;
028import org.apache.commons.fileupload.FileUpload;
029import org.apache.commons.fileupload.FileUploadBase;
030import org.apache.commons.fileupload.FileUploadException;
031
032/**
033 * <p>High level API for processing file uploads.</p>
034 *
035 * <p>This class handles multiple files per single HTML widget, sent using
036 * <code>multipart/mixed</code> encoding type, as specified by
037 * <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.  Use
038 * {@link org.apache.commons.fileupload.servlet.ServletFileUpload
039 * #parseRequest(javax.servlet.http.HttpServletRequest)} to acquire a list
040 * of {@link org.apache.commons.fileupload.FileItem FileItems} associated
041 * with a given HTML widget.</p>
042 *
043 * <p>How the data for individual parts is stored is determined by the factory
044 * used to create them; a given part may be in memory, on disk, or somewhere
045 * else.</p>
046 *
047 * @since FileUpload 1.1
048 *
049 * @version $Id: PortletFileUpload.java 1455537 2013-03-12 14:06:11Z simonetripodi $
050 */
051public class PortletFileUpload extends FileUpload {
052
053    // ---------------------------------------------------------- Class methods
054
055    /**
056     * Utility method that determines whether the request contains multipart
057     * content.
058     *
059     * @param request The portlet request to be evaluated. Must be non-null.
060     *
061     * @return <code>true</code> if the request is multipart;
062     *         <code>false</code> otherwise.
063     */
064    public static final boolean isMultipartContent(ActionRequest request) {
065        return FileUploadBase.isMultipartContent(
066                new PortletRequestContext(request));
067    }
068
069    // ----------------------------------------------------------- Constructors
070
071    /**
072     * Constructs an uninitialised instance of this class. A factory must be
073     * configured, using <code>setFileItemFactory()</code>, before attempting
074     * to parse requests.
075     *
076     * @see FileUpload#FileUpload(FileItemFactory)
077     */
078    public PortletFileUpload() {
079        super();
080    }
081
082    /**
083     * Constructs an instance of this class which uses the supplied factory to
084     * create <code>FileItem</code> instances.
085     *
086     * @see FileUpload#FileUpload()
087     * @param fileItemFactory The factory to use for creating file items.
088     */
089    public PortletFileUpload(FileItemFactory fileItemFactory) {
090        super(fileItemFactory);
091    }
092
093    // --------------------------------------------------------- Public methods
094
095    /**
096     * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
097     * compliant <code>multipart/form-data</code> stream.
098     *
099     * @param request The portlet request to be parsed.
100     *
101     * @return A list of <code>FileItem</code> instances parsed from the
102     *         request, in the order that they were transmitted.
103     *
104     * @throws FileUploadException if there are problems reading/parsing
105     *                             the request or storing files.
106     */
107    public List<FileItem> parseRequest(ActionRequest request)
108            throws FileUploadException {
109        return parseRequest(new PortletRequestContext(request));
110    }
111
112    /**
113     * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
114     * compliant <code>multipart/form-data</code> stream.
115     *
116     * @param request The portlet request to be parsed.
117     *
118     * @return A map of <code>FileItem</code> instances parsed from the request.
119     *
120     * @throws FileUploadException if there are problems reading/parsing
121     *                             the request or storing files.
122     *
123     * @since 1.3
124     */
125    public Map<String, List<FileItem>> parseParameterMap(ActionRequest request)
126            throws FileUploadException {
127        return parseParameterMap(new PortletRequestContext(request));
128    }
129
130    /**
131     * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
132     * compliant <code>multipart/form-data</code> stream.
133     *
134     * @param request The portlet request to be parsed.
135     *
136     * @return An iterator to instances of <code>FileItemStream</code>
137     *         parsed from the request, in the order that they were
138     *         transmitted.
139     *
140     * @throws FileUploadException if there are problems reading/parsing
141     *                             the request or storing files.
142     * @throws IOException An I/O error occurred. This may be a network
143     *   error while communicating with the client or a problem while
144     *   storing the uploaded content.
145     */
146    public FileItemIterator getItemIterator(ActionRequest request)
147            throws FileUploadException, IOException {
148        return super.getItemIterator(new PortletRequestContext(request));
149    }
150
151}