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