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