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 030 /** 031 * <p> This service handles parsing <code>multipart/form-data</code> 032 * POST requests and turing them into form fields and uploaded files. 033 * This can be either performed automatically by the {@link 034 * org.apache.fulcrum.util.parser.ParameterParser} or manually by an user 035 * definded {@link org.apache.turbine.modules.Action}. 036 * 037 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a> 038 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a> 039 * @version $Id: UploadService.java 732085 2009-01-06 19:58:22Z tv $ 040 */ 041 public interface UploadService 042 043 { 044 /** Avalon Identifier **/ 045 String ROLE = UploadService.class.getName(); 046 047 /** 048 * HTTP header. 049 */ 050 String CONTENT_TYPE = "Content-type"; 051 052 /** 053 * HTTP header. 054 */ 055 String CONTENT_DISPOSITION = "Content-disposition"; 056 057 /** 058 * HTTP header base type. 059 */ 060 String MULTIPART = "multipart"; 061 062 /** 063 * HTTP header base type modifier. 064 */ 065 String FORM_DATA = "form-data"; 066 067 /** 068 * HTTP header base type modifier. 069 */ 070 String MIXED = "mixed"; 071 072 /** 073 * HTTP header. 074 */ 075 String MULTIPART_FORM_DATA = 076 MULTIPART + '/' + FORM_DATA; 077 078 /** 079 * HTTP header. 080 */ 081 String MULTIPART_MIXED = MULTIPART + '/' + MIXED; 082 083 /** 084 * The request parameter name for overriding 'repository' property 085 * (path). 086 */ 087 String REPOSITORY_PARAMETER = "path"; 088 089 /** 090 * The key in UploadService properties in 091 * TurbineResources.properties 'repository' property. 092 */ 093 String REPOSITORY_KEY = "repository"; 094 095 /** 096 * <p> The default value of 'repository' property (.). This is 097 * the directory where uploaded fiels will get stored temporarily. 098 * Note that "." is whatever the servlet container chooses to be 099 * it's 'current directory'. 100 */ 101 String REPOSITORY_DEFAULT = "."; 102 103 /** 104 * w The key in UploadService properties in 105 * service configuration 'sizeMax' property. 106 */ 107 String SIZE_MAX_KEY = "sizeMax"; 108 109 /** 110 * <p> The default value of 'sizMax' property (1 megabyte = 111 * 1048576 bytes). This is the maximum size of POST request that 112 * will be parsed by the uploader. If you need to set specific 113 * limits for your users, set this property to the largest limit 114 * value, and use an action + no auto upload to enforce limits. 115 * 116 */ 117 int SIZE_MAX_DEFAULT = 1048576; 118 119 /** 120 * The key in UploadService properties in 121 * TurbineResources.properties 'sizeThreshold' property. 122 */ 123 String SIZE_THRESHOLD_KEY = "sizeThreshold"; 124 125 /** 126 * <p> The default value of 'sizeThreshold' property (10 127 * kilobytes = 10240 bytes). This is the maximum size of a POST 128 * request that will have it's components stored temporarily in 129 * memory, instead of disk. 130 */ 131 int SIZE_THRESHOLD_DEFAULT = 10240; 132 133 /** 134 * The key in UploadService properties in 135 * TurbineResources.properties 'headerEncoding' property. 136 */ 137 String HEADER_ENCODING_KEY = "headerEncoding"; 138 139 /** 140 * <p> The default value of 'headerEncoding' property (.). 141 * The value has been decided by copying from DiskFileItem class 142 */ 143 String HEADER_ENCODING_DEFAULT = "ISO-8859-1"; 144 145 /** 146 * <p>Parses a <a href="http://rf.cx/rfc1867.html">RFC 1867</a> 147 * compliant <code>multipart/form-data</code> stream.</p> 148 * 149 * @param req The servlet request to be parsed. 150 * @exception ServiceException Problems reading/parsing the 151 * request or storing the uploaded file(s). 152 */ 153 List parseRequest(HttpServletRequest req) 154 throws ServiceException; 155 156 /** 157 * <p>Parses a <a href="http://rf.cx/rfc1867.html">RFC 1867</a> 158 * compliant <code>multipart/form-data</code> stream.</p> 159 * 160 * @param req The servlet request to be parsed. 161 * @param path The location where the files should be stored. 162 * @exception ServiceException Problems reading/parsing the 163 * request or storing the uploaded file(s). 164 */ 165 List parseRequest(HttpServletRequest req, String path) 166 throws ServiceException; 167 168 /** 169 * <p>Parses a <a href="http://rf.cx/rfc1867.html">RFC 1867</a> 170 * compliant <code>multipart/form-data</code> stream.</p> 171 * 172 * @param req The servlet request to be parsed. 173 * @param sizeThreshold the max size in bytes to be stored in memory 174 * @param sizeMax the maximum allowed upload size in bytes 175 * @param path The location where the files should be stored. 176 * @exception ServiceException Problems reading/parsing the 177 * request or storing the uploaded file(s). 178 */ 179 List parseRequest(HttpServletRequest req, int sizeThreshold, 180 int sizeMax, String path) 181 throws ServiceException; 182 183 /** 184 * <p> Retrieves the value of <code>size.max</code> property of the 185 * {@link org.apache.fulcrum.upload.UploadService}. 186 * 187 * @return The maximum upload size. 188 */ 189 long getSizeMax(); 190 191 /** 192 * <p> Retrieves the value of <code>size.threshold</code> property of 193 * {@link org.apache.fulcrum.upload.UploadService}. 194 * 195 * @return The threshold beyond which files are written directly to disk. 196 */ 197 long getSizeThreshold(); 198 199 /** 200 * <p> Retrieves the value of the <code>repository</code> property of 201 * {@link org.apache.fulcrum.upload.UploadService}. 202 * 203 * @return The repository. 204 */ 205 String getRepository(); 206 207 /** 208 * <p> Retrieves the value of the <code>headerEncoding</code> property of 209 * {@link org.apache.fulcrum.upload.UploadService}. 210 * 211 * @return Returns the headerEncoding. 212 */ 213 String getHeaderEncoding(); 214 }