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} 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 */
049public class PortletFileUpload extends FileUpload {
050
051    /**
052     * Utility method that determines whether the request contains multipart
053     * content.
054     *
055     * @param request The portlet request to be evaluated. Must be non-null.
056     * @return {@code true} if the request is multipart;
057     *         {@code false} otherwise.
058     */
059    public static final boolean isMultipartContent(final ActionRequest request) {
060        return FileUploadBase.isMultipartContent(
061                new PortletRequestContext(request));
062    }
063
064    /**
065     * Constructs an uninitialized instance of this class. A factory must be
066     * configured, using {@code setFileItemFactory()}, before attempting
067     * to parse requests.
068     *
069     * @see FileUpload#FileUpload(FileItemFactory)
070     */
071    public PortletFileUpload() {
072    }
073
074    /**
075     * Constructs an instance of this class which uses the supplied factory to
076     * create {@code FileItem} instances.
077     *
078     * @see FileUpload#FileUpload()
079     * @param fileItemFactory The factory to use for creating file items.
080     */
081    public PortletFileUpload(final FileItemFactory fileItemFactory) {
082        super(fileItemFactory);
083    }
084
085    /**
086     * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
087     * compliant {@code multipart/form-data} stream.
088     *
089     * @param request The portlet request to be parsed.
090     * @return An iterator to instances of {@code FileItemStream}
091     *         parsed from the request, in the order that they were
092     *         transmitted.
093     *
094     * @throws FileUploadException if there are problems reading/parsing
095     *                             the request or storing files.
096     * @throws IOException An I/O error occurred. This may be a network
097     *   error while communicating with the client or a problem while
098     *   storing the uploaded content.
099     */
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}