View Javadoc

1   package org.apache.turbine.services.upload;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
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 }