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