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    }