001 package org.apache.fulcrum.upload; 002 003 004 /* 005 * Licensed to the Apache Software Foundation (ASF) under one 006 * or more contributor license agreements. See the NOTICE file 007 * distributed with this work for additional information 008 * regarding copyright ownership. The ASF licenses this file 009 * to you under the Apache License, Version 2.0 (the 010 * "License"); you may not use this file except in compliance 011 * with the License. You may obtain a copy of the License at 012 * 013 * http://www.apache.org/licenses/LICENSE-2.0 014 * 015 * Unless required by applicable law or agreed to in writing, 016 * software distributed under the License is distributed on an 017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 018 * KIND, either express or implied. See the License for the 019 * specific language governing permissions and limitations 020 * under the License. 021 */ 022 023 024 import java.util.List; 025 026 import javax.servlet.http.HttpServletRequest; 027 028 import org.apache.avalon.framework.service.ServiceException; 029 import org.apache.commons.fileupload.FileItem; 030 import org.apache.commons.fileupload.FileItemIterator; 031 032 /** 033 * <p> This service handles parsing <code>multipart/form-data</code> 034 * POST requests and turning them into form fields and uploaded files. 035 * This can be either performed automatically by the {@link 036 * org.apache.fulcrum.parser.ParameterParser} or manually by an user 037 * defined {@link org.apache.turbine.modules.Action}. 038 * 039 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a> 040 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a> 041 * @version $Id: UploadService.java 1351114 2012-06-17 15:59:20Z tv $ 042 */ 043 public interface UploadService 044 045 { 046 /** Avalon Identifier **/ 047 String ROLE = UploadService.class.getName(); 048 049 /** 050 * HTTP header. 051 */ 052 String CONTENT_TYPE = "Content-type"; 053 054 /** 055 * HTTP header. 056 */ 057 String CONTENT_DISPOSITION = "Content-disposition"; 058 059 /** 060 * HTTP header base type. 061 */ 062 String MULTIPART = "multipart"; 063 064 /** 065 * HTTP header base type modifier. 066 */ 067 String FORM_DATA = "form-data"; 068 069 /** 070 * HTTP header base type modifier. 071 */ 072 String MIXED = "mixed"; 073 074 /** 075 * HTTP header. 076 */ 077 String MULTIPART_FORM_DATA = 078 MULTIPART + '/' + FORM_DATA; 079 080 /** 081 * HTTP header. 082 */ 083 String MULTIPART_MIXED = MULTIPART + '/' + MIXED; 084 085 /** 086 * The request parameter name for overriding 'repository' property 087 * (path). 088 */ 089 String REPOSITORY_PARAMETER = "path"; 090 091 /** 092 * The key in UploadService properties in 093 * TurbineResources.properties 'repository' property. 094 */ 095 String REPOSITORY_KEY = "repository"; 096 097 /** 098 * <p> The default value of 'repository' property (.). This is 099 * the directory where uploaded files will get stored temporarily. 100 * Note that "." is whatever the servlet container chooses to be 101 * it's 'current directory'. 102 */ 103 String REPOSITORY_DEFAULT = "."; 104 105 /** 106 * w The key in UploadService properties in 107 * service configuration 'sizeMax' property. 108 */ 109 String SIZE_MAX_KEY = "sizeMax"; 110 111 /** 112 * <p> The default value of 'sizMax' property (1 megabyte = 113 * 1048576 bytes). This is the maximum size of POST request that 114 * will be parsed by the uploader. If you need to set specific 115 * limits for your users, set this property to the largest limit 116 * value, and use an action + no auto upload to enforce limits. 117 * 118 */ 119 int SIZE_MAX_DEFAULT = 1048576; 120 121 /** 122 * The key in UploadService properties in 123 * TurbineResources.properties 'sizeThreshold' property. 124 */ 125 String SIZE_THRESHOLD_KEY = "sizeThreshold"; 126 127 /** 128 * <p> The default value of 'sizeThreshold' property (10 129 * kilobytes = 10240 bytes). This is the maximum size of a POST 130 * request that will have it's components stored temporarily in 131 * memory, instead of disk. 132 */ 133 int SIZE_THRESHOLD_DEFAULT = 10240; 134 135 /** 136 * The key in UploadService properties in 137 * TurbineResources.properties 'headerEncoding' property. 138 */ 139 String HEADER_ENCODING_KEY = "headerEncoding"; 140 141 /** 142 * <p> The default value of 'headerEncoding' property (.). 143 * The value has been decided by copying from DiskFileItem class 144 */ 145 String HEADER_ENCODING_DEFAULT = "ISO-8859-1"; 146 147 /** 148 * <p>Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> 149 * compliant <code>multipart/form-data</code> stream.</p> 150 * 151 * @param req The servlet request to be parsed. 152 * @exception ServiceException Problems reading/parsing the 153 * request or storing the uploaded file(s). 154 */ 155 List<FileItem> parseRequest(HttpServletRequest req) 156 throws ServiceException; 157 158 /** 159 * <p>Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> 160 * compliant <code>multipart/form-data</code> stream.</p> 161 * 162 * @param req The servlet request to be parsed. 163 * @param path The location where the files should be stored. 164 * @exception ServiceException Problems reading/parsing the 165 * request or storing the uploaded file(s). 166 */ 167 List<FileItem> parseRequest(HttpServletRequest req, String path) 168 throws ServiceException; 169 170 /** 171 * <p>Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> 172 * compliant <code>multipart/form-data</code> stream.</p> 173 * 174 * @param req The servlet request to be parsed. 175 * @param sizeThreshold the max size in bytes to be stored in memory 176 * @param sizeMax the maximum allowed upload size in bytes 177 * @param path The location where the files should be stored. 178 * @exception ServiceException Problems reading/parsing the 179 * request or storing the uploaded file(s). 180 */ 181 List<FileItem> parseRequest(HttpServletRequest req, int sizeThreshold, 182 int sizeMax, String path) 183 throws ServiceException; 184 185 186 /** 187 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> 188 * compliant <code>multipart/form-data</code> stream. 189 * 190 * @param req The servlet request to be parsed. 191 * 192 * @return An iterator to instances of <code>FileItemStream</code> 193 * parsed from the request, in the order that they were 194 * transmitted. 195 * 196 * @throws ServiceException if there are problems reading/parsing 197 * the request or storing files. This 198 * may also be a network error while 199 * communicating with the client or a 200 * problem while storing the uploaded 201 * content. 202 */ 203 FileItemIterator getItemIterator(HttpServletRequest req) throws ServiceException; 204 205 206 /** 207 * <p> Retrieves the value of <code>size.max</code> property of the 208 * {@link org.apache.fulcrum.upload.UploadService}. 209 * 210 * @return The maximum upload size. 211 */ 212 long getSizeMax(); 213 214 /** 215 * <p> Retrieves the value of <code>size.threshold</code> property of 216 * {@link org.apache.fulcrum.upload.UploadService}. 217 * 218 * @return The threshold beyond which files are written directly to disk. 219 */ 220 long getSizeThreshold(); 221 222 /** 223 * <p> Retrieves the value of the <code>repository</code> property of 224 * {@link org.apache.fulcrum.upload.UploadService}. 225 * 226 * @return The repository. 227 */ 228 String getRepository(); 229 230 /** 231 * <p> Retrieves the value of the <code>headerEncoding</code> property of 232 * {@link org.apache.fulcrum.upload.UploadService}. 233 * 234 * @return Returns the headerEncoding. 235 */ 236 String getHeaderEncoding(); 237 238 /** 239 * Utility method that determines whether the request contains multipart 240 * content. 241 * 242 * @param req The servlet request to be evaluated. Must be non-null. 243 * 244 * @return <code>true</code> if the request is multipart; 245 * <code>false</code> otherwise. 246 */ 247 boolean isMultipart(HttpServletRequest req); 248 249 }