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.servlet; 018 019import java.io.IOException; 020import java.util.List; 021import java.util.Map; 022 023import javax.servlet.http.HttpServletRequest; 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 {@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 */ 046public class ServletFileUpload extends FileUpload { 047 048 /** 049 * Constant for HTTP POST method. 050 */ 051 private static final String POST_METHOD = "POST"; 052 053 // ---------------------------------------------------------- Class methods 054 055 /** 056 * Utility method that determines whether the request contains multipart 057 * content. 058 * 059 * @param request The servlet 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( 065 HttpServletRequest request) { 066 if (!POST_METHOD.equalsIgnoreCase(request.getMethod())) { 067 return false; 068 } 069 return FileUploadBase.isMultipartContent(new ServletRequestContext(request)); 070 } 071 072 // ----------------------------------------------------------- Constructors 073 074 /** 075 * Constructs an uninitialised instance of this class. A factory must be 076 * configured, using <code>setFileItemFactory()</code>, before attempting 077 * to parse requests. 078 * 079 * @see FileUpload#FileUpload(FileItemFactory) 080 */ 081 public ServletFileUpload() { 082 super(); 083 } 084 085 /** 086 * Constructs an instance of this class which uses the supplied factory to 087 * create <code>FileItem</code> instances. 088 * 089 * @see FileUpload#FileUpload() 090 * @param fileItemFactory The factory to use for creating file items. 091 */ 092 public ServletFileUpload(FileItemFactory fileItemFactory) { 093 super(fileItemFactory); 094 } 095 096 // --------------------------------------------------------- Public methods 097 098 /** 099 * 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}