001: package org.apache.turbine.services.upload;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import javax.servlet.http.HttpServletRequest;
023:
024: import org.apache.turbine.services.Service;
025: import org.apache.turbine.util.TurbineException;
026: import org.apache.turbine.util.parser.ParameterParser;
027:
028: /**
029: * <p> This service handles parsing <code>multipart/form-data</code>
030: * POST requests and turing them into form fields and uploaded files.
031: * This can be either performed automatically by the {@link
032: * org.apache.turbine.util.parser.ParameterParser} or manually by an user
033: * definded {@link org.apache.turbine.modules.Action}.
034: *
035: * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
036: * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
037: * @version $Id: UploadService.java 534527 2007-05-02 16:10:59Z tv $
038: */
039: public interface UploadService extends Service {
040: /**
041: * HTTP header.
042: */
043: String CONTENT_TYPE = "Content-type";
044:
045: /**
046: * HTTP header.
047: */
048: String CONTENT_DISPOSITION = "Content-disposition";
049:
050: /**
051: * HTTP header base type.
052: */
053: String MULTIPART = "multipart";
054:
055: /**
056: * HTTP header base type modifier.
057: */
058: String FORM_DATA = "form-data";
059:
060: /**
061: * HTTP header base type modifier.
062: */
063: String MIXED = "mixed";
064:
065: /**
066: * HTTP header.
067: */
068: String MULTIPART_FORM_DATA = MULTIPART + '/' + FORM_DATA;
069:
070: /**
071: * HTTP header.
072: */
073: String MULTIPART_MIXED = MULTIPART + '/' + MIXED;
074:
075: /**
076: * The key in the TurbineResources.properties that references this
077: * service.
078: */
079: String SERVICE_NAME = "UploadService";
080:
081: /**
082: * The key in UploadService properties in
083: * TurbineResources.properties 'automatic' property.
084: */
085: String AUTOMATIC_KEY = "automatic";
086:
087: /**
088: * <p> The default value of 'automatic' property
089: * (<code>false</code>). If set to <code>true</code>, parsing the
090: * multipart request will be performed automaticaly by {@link
091: * org.apache.turbine.util.parser.ParameterParser}. Otherwise, an {@link
092: * org.apache.turbine.modules.Action} may decide to to parse the
093: * request by calling {@link #parseRequest(HttpServletRequest,
094: * ParameterParser, String) parseRequest} manually.
095: */
096: boolean AUTOMATIC_DEFAULT = false;
097:
098: /**
099: * 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, ParameterParser params,
160: String path) throws TurbineException;
161:
162: /**
163: * <p> Retrieves the value of <code>size.max</code> property of the
164: * {@link org.apache.turbine.services.upload.UploadService}.
165: *
166: * @return The maximum upload size.
167: */
168: long getSizeMax();
169:
170: /**
171: * <p> Retrieves the value of <code>size.threshold</code> property of
172: * {@link org.apache.turbine.services.upload.UploadService}.
173: *
174: * @return The threshold beyond which files are written directly to disk.
175: */
176: int getSizeThreshold();
177:
178: /**
179: * <p> Retrieves the value of the <code>repository</code> property of
180: * {@link org.apache.turbine.services.upload.UploadService}.
181: *
182: * @return The repository.
183: */
184: String getRepository();
185:
186: /**
187: * <p> Retrieves the value of 'automatic' property of {@link
188: * UploadService}.
189: *
190: * @return The value of 'automatic' property of {@link
191: * UploadService}.
192: */
193: boolean getAutomatic();
194: }
|