1 package org.apache.turbine.services.upload;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import javax.servlet.http.HttpServletRequest;
20
21 import org.apache.turbine.services.Service;
22 import org.apache.turbine.util.TurbineException;
23 import org.apache.turbine.util.parser.ParameterParser;
24
25 /***
26 * <p> This service handles parsing <code>multipart/form-data</code>
27 * POST requests and turing them into form fields and uploaded files.
28 * This can be either performed automatically by the {@link
29 * org.apache.turbine.util.parser.ParameterParser} or manually by an user
30 * definded {@link org.apache.turbine.modules.Action}.
31 *
32 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
33 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
34 * @version $Id: UploadService.java 279820 2005-09-09 17:05:54Z henning $
35 */
36 public interface UploadService
37 extends Service
38 {
39 /***
40 * HTTP header.
41 */
42 String CONTENT_TYPE = "Content-type";
43
44 /***
45 * HTTP header.
46 */
47 String CONTENT_DISPOSITION = "Content-disposition";
48
49 /***
50 * HTTP header base type.
51 */
52 String MULTIPART = "multipart";
53
54 /***
55 * HTTP header base type modifier.
56 */
57 String FORM_DATA = "form-data";
58
59 /***
60 * HTTP header base type modifier.
61 */
62 String MIXED = "mixed";
63
64 /***
65 * HTTP header.
66 */
67 String MULTIPART_FORM_DATA =
68 MULTIPART + '/' + FORM_DATA;
69
70 /***
71 * HTTP header.
72 */
73 String MULTIPART_MIXED = MULTIPART + '/' + MIXED;
74
75 /***
76 * The key in the TurbineResources.properties that references this
77 * service.
78 */
79 String SERVICE_NAME = "UploadService";
80
81 /***
82 * The key in UploadService properties in
83 * TurbineResources.properties 'automatic' property.
84 */
85 String AUTOMATIC_KEY = "automatic";
86
87 /***
88 * <p> The default value of 'automatic' property
89 * (<code>false</code>). If set to <code>true</code>, parsing the
90 * multipart request will be performed automaticaly by {@link
91 * org.apache.turbine.util.parser.ParameterParser}. Otherwise, an {@link
92 * org.apache.turbine.modules.Action} may decide to to parse the
93 * request by calling {@link #parseRequest(HttpServletRequest,
94 * ParameterParser, String) parseRequest} manually.
95 */
96 boolean AUTOMATIC_DEFAULT = false;
97
98 /***
99 * The request parameter name for overriding 'repository' property
100 * (path).
101 */
102 String REPOSITORY_PARAMETER = "path";
103
104 /***
105 * The key in UploadService properties in
106 * TurbineResources.properties 'repository' property.
107 */
108 String REPOSITORY_KEY = "repository";
109
110 /***
111 * <p> The default value of 'repository' property (.). This is
112 * the directory where uploaded fiels will get stored temporarily.
113 * Note that "." is whatever the servlet container chooses to be
114 * it's 'current directory'.
115 */
116 String REPOSITORY_DEFAULT = ".";
117
118 /***
119 * The key in UploadService properties in
120 * TurbineResources.properties 'size.max' property.
121 */
122 String SIZE_MAX_KEY = "size.max";
123
124 /***
125 * <p> The default value of 'size.max' property (1 megabyte =
126 * 1048576 bytes). This is the maximum size of POST request that
127 * will be parsed by the uploader. If you need to set specific
128 * limits for your users, set this property to the largest limit
129 * value, and use an action + no auto upload to enforce limits.
130 *
131 */
132 long SIZE_MAX_DEFAULT = 1048576;
133
134 /***
135 * The key in UploadService properties in
136 * TurbineResources.properties 'size.threshold' property.
137 */
138 String SIZE_THRESHOLD_KEY = "size.threshold";
139
140 /***
141 * <p> The default value of 'size.threshold' property (10
142 * kilobytes = 10240 bytes). This is the maximum size of a POST
143 * request that will have it's components stored temporarily in
144 * memory, instead of disk.
145 */
146 int SIZE_THRESHOLD_DEFAULT = 10240;
147
148 /***
149 * <p> This method performs parsing the request, and storing the
150 * acquired information in apropriate places.
151 *
152 * @param req The servlet request to be parsed.
153 * @param params The ParameterParser instance to insert form
154 * fields into.
155 * @param path The location where the files should be stored.
156 * @exception TurbineException Problems reading/parsing the
157 * request or storing the uploaded file(s).
158 */
159 void parseRequest(HttpServletRequest req,
160 ParameterParser params,
161 String path)
162 throws TurbineException;
163
164 /***
165 * <p> Retrieves the value of <code>size.max</code> property of the
166 * {@link org.apache.turbine.services.upload.UploadService}.
167 *
168 * @return The maximum upload size.
169 */
170 long getSizeMax();
171
172 /***
173 * <p> Retrieves the value of <code>size.threshold</code> property of
174 * {@link org.apache.turbine.services.upload.UploadService}.
175 *
176 * @return The threshold beyond which files are written directly to disk.
177 */
178 int getSizeThreshold();
179
180 /***
181 * <p> Retrieves the value of the <code>repository</code> property of
182 * {@link org.apache.turbine.services.upload.UploadService}.
183 *
184 * @return The repository.
185 */
186 String getRepository();
187
188 /***
189 * <p> Retrieves the value of 'automatic' property of {@link
190 * UploadService}.
191 *
192 * @return The value of 'automatic' property of {@link
193 * UploadService}.
194 */
195 boolean getAutomatic();
196 }