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    }