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.servlet;
18
19 import java.io.IOException;
20 import java.util.List;
21 import java.util.Map;
22
23 import javax.servlet.http.HttpServletRequest;
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 {@link
38 * #parseRequest(HttpServletRequest)} to acquire a list of {@link
39 * org.apache.commons.fileupload.FileItem}s associated with a given HTML
40 * widget.</p>
41 *
42 * <p>How the data for individual parts is stored is determined by the factory
43 * used to create them; a given part may be in memory, on disk, or somewhere
44 * else.</p>
45 */
46 public class ServletFileUpload extends FileUpload {
47
48 /**
49 * Constant for HTTP POST method.
50 */
51 private static final String POST_METHOD = "POST";
52
53 // ---------------------------------------------------------- Class methods
54
55 /**
56 * Utility method that determines whether the request contains multipart
57 * content.
58 *
59 * @param request The servlet request to be evaluated. Must be non-null.
60 *
61 * @return <code>true</code> if the request is multipart;
62 * <code>false</code> otherwise.
63 */
64 public static final boolean isMultipartContent(
65 HttpServletRequest request) {
66 if (!POST_METHOD.equalsIgnoreCase(request.getMethod())) {
67 return false;
68 }
69 return FileUploadBase.isMultipartContent(new ServletRequestContext(request));
70 }
71
72 // ----------------------------------------------------------- Constructors
73
74 /**
75 * Constructs an uninitialised instance of this class. A factory must be
76 * configured, using <code>setFileItemFactory()</code>, before attempting
77 * to parse requests.
78 *
79 * @see FileUpload#FileUpload(FileItemFactory)
80 */
81 public ServletFileUpload() {
82 super();
83 }
84
85 /**
86 * Constructs an instance of this class which uses the supplied factory to
87 * create <code>FileItem</code> instances.
88 *
89 * @see FileUpload#FileUpload()
90 * @param fileItemFactory The factory to use for creating file items.
91 */
92 public ServletFileUpload(FileItemFactory fileItemFactory) {
93 super(fileItemFactory);
94 }
95
96 // --------------------------------------------------------- Public methods
97
98 /**
99 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
100 * compliant <code>multipart/form-data</code> stream.
101 *
102 * @param request The servlet request to be parsed.
103 *
104 * @return A list of <code>FileItem</code> instances parsed from the
105 * request, in the order that they were transmitted.
106 *
107 * @throws FileUploadException if there are problems reading/parsing
108 * the request or storing files.
109 */
110 @Override
111 public List<FileItem> parseRequest(HttpServletRequest request)
112 throws FileUploadException {
113 return parseRequest(new ServletRequestContext(request));
114 }
115
116 /**
117 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
118 * compliant <code>multipart/form-data</code> stream.
119 *
120 * @param request The servlet request to be parsed.
121 *
122 * @return A map of <code>FileItem</code> instances parsed from the request.
123 *
124 * @throws FileUploadException if there are problems reading/parsing
125 * the request or storing files.
126 *
127 * @since 1.3
128 */
129 public Map<String, List<FileItem>> parseParameterMap(HttpServletRequest request)
130 throws FileUploadException {
131 return parseParameterMap(new ServletRequestContext(request));
132 }
133
134 /**
135 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
136 * compliant <code>multipart/form-data</code> stream.
137 *
138 * @param request The servlet request to be parsed.
139 *
140 * @return An iterator to instances of <code>FileItemStream</code>
141 * parsed from the request, in the order that they were
142 * transmitted.
143 *
144 * @throws FileUploadException if there are problems reading/parsing
145 * the request or storing files.
146 * @throws IOException An I/O error occurred. This may be a network
147 * error while communicating with the client or a problem while
148 * storing the uploaded content.
149 */
150 public FileItemIterator getItemIterator(HttpServletRequest request)
151 throws FileUploadException, IOException {
152 return super.getItemIterator(new ServletRequestContext(request));
153 }
154
155 }