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} 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 /** 054 * Utility method that determines whether the request contains multipart 055 * content. 056 * 057 * @param request The servlet request to be evaluated. Must be non-null. 058 * @return {@code true} if the request is multipart; 059 * {@code false} otherwise. 060 */ 061 public static final boolean isMultipartContent( 062 final HttpServletRequest request) { 063 if (!POST_METHOD.equalsIgnoreCase(request.getMethod())) { 064 return false; 065 } 066 return FileUploadBase.isMultipartContent(new ServletRequestContext(request)); 067 } 068 069 /** 070 * Constructs an uninitialized instance of this class. A factory must be 071 * configured, using {@code setFileItemFactory()}, before attempting 072 * to parse requests. 073 * 074 * @see FileUpload#FileUpload(FileItemFactory) 075 */ 076 public ServletFileUpload() { 077 } 078 079 /** 080 * Constructs an instance of this class which uses the supplied factory to 081 * create {@code FileItem} instances. 082 * 083 * @see FileUpload#FileUpload() 084 * @param fileItemFactory The factory to use for creating file items. 085 */ 086 public ServletFileUpload(final FileItemFactory fileItemFactory) { 087 super(fileItemFactory); 088 } 089 090 /** 091 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> 092 * compliant {@code multipart/form-data} stream. 093 * 094 * @param request The servlet request to be parsed. 095 * @return An iterator to instances of {@code FileItemStream} 096 * parsed from the request, in the order that they were 097 * transmitted. 098 * 099 * @throws FileUploadException if there are problems reading/parsing 100 * the request or storing files. 101 * @throws IOException An I/O error occurred. This may be a network 102 * error while communicating with the client or a problem while 103 * storing the uploaded content. 104 */ 105 public FileItemIterator getItemIterator(final HttpServletRequest request) 106 throws FileUploadException, IOException { 107 return super.getItemIterator(new ServletRequestContext(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} stream. 113 * 114 * @param request The servlet request to be parsed. 115 * @return A map of {@code FileItem} instances parsed from the request. 116 * @throws FileUploadException if there are problems reading/parsing 117 * the request or storing files. 118 * 119 * @since 1.3 120 */ 121 public Map<String, List<FileItem>> parseParameterMap(final HttpServletRequest request) 122 throws FileUploadException { 123 return parseParameterMap(new ServletRequestContext(request)); 124 } 125 126 /** 127 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> 128 * compliant {@code multipart/form-data} stream. 129 * 130 * @param request The servlet request to be parsed. 131 * @return A list of {@code FileItem} instances parsed from the 132 * request, in the order that they were transmitted. 133 * 134 * @throws FileUploadException if there are problems reading/parsing 135 * the request or storing files. 136 */ 137 @Override 138 public List<FileItem> parseRequest(final HttpServletRequest request) 139 throws FileUploadException { 140 return parseRequest(new ServletRequestContext(request)); 141 } 142 143}