![JAR search and dependency download from the Maven repository](/logo.png)
org.apache.fulcrum.upload.UploadService Maven / Gradle / Ivy
package org.apache.fulcrum.upload;
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
import java.util.List;
import jakarta.servlet.http.HttpServletRequest;
import org.apache.avalon.framework.service.ServiceException;
import org.apache.commons.fileupload2.core.FileItem;
import org.apache.commons.fileupload2.core.FileItemInputIterator;
/**
*
* This service handles parsing multipart/form-data
POST requests
* and turning them into form fields and uploaded files. This can be either
* performed automatically by the org.apache.fulcrum.parser.ParameterParser
or manually by a user
* defined org.apache.turbine.modules.Action
.
*
* @author Rafal Krzewski
* @author Daniel Rall
* @version $Id$
*/
public interface UploadService
{
/** Avalon Identifier **/
String ROLE = UploadService.class.getName();
/**
* HTTP header.
*/
String CONTENT_TYPE = "Content-type";
/**
* HTTP header.
*/
String CONTENT_DISPOSITION = "Content-disposition";
/**
* HTTP header base type.
*/
String MULTIPART = "multipart";
/**
* HTTP header base type modifier.
*/
String FORM_DATA = "form-data";
/**
* HTTP header base type modifier.
*/
String MIXED = "mixed";
/**
* HTTP header.
*/
String MULTIPART_FORM_DATA = MULTIPART + '/' + FORM_DATA;
/**
* HTTP header.
*/
String MULTIPART_MIXED = MULTIPART + '/' + MIXED;
/**
* The request parameter name for overriding 'repository' property (path).
*/
String REPOSITORY_PARAMETER = "path";
/**
* The key in UploadService properties in TurbineResources.properties
* 'repository' property.
*/
String REPOSITORY_KEY = "repository";
/**
*
* The default value of 'repository' property (.). This is the directory where
* uploaded files will get stored temporarily. Note that "." is whatever the
* servlet container chooses to be it's 'current directory'.
*/
String REPOSITORY_DEFAULT = ".";
/**
* w The key in UploadService properties in service configuration 'sizeMax'
* property.
*/
String SIZE_MAX_KEY = "sizeMax";
/**
*
* The default value of 'sizMax' property (1 megabyte = 1048576 bytes). This is
* the maximum size of POST request that will be parsed by the uploader. If you
* need to set specific limits for your users, set this property to the largest
* limit value, and use an action + no auto upload to enforce limits.
*
*/
int SIZE_MAX_DEFAULT = 1048576;
/**
* The key in UploadService properties in TurbineResources.properties
* 'sizeThreshold' property.
*/
String SIZE_THRESHOLD_KEY = "sizeThreshold";
/**
*
* The default value of 'sizeThreshold' property (10 kilobytes = 10240 bytes).
* This is the maximum size of a POST request that will have it's components
* stored temporarily in memory, instead of disk.
*/
int SIZE_THRESHOLD_DEFAULT = 10240;
/**
* The key in UploadService properties in TurbineResources.properties
* 'headerEncoding' property.
*/
String HEADER_ENCODING_KEY = "headerEncoding";
/**
*
* The default value of 'headerEncoding' property (.). The value has been
* decided by copying from DiskFileItem class
*/
String HEADER_ENCODING_DEFAULT = "ISO-8859-1";
/**
*
* Parses a RFC 1867 compliant
* multipart/form-data
stream.
*
*
* @param req The servlet request to be parsed.
* @return list of file items
* @throws ServiceException Problems reading/parsing the request or storing
* the uploaded file(s).
*/
List parseRequest(HttpServletRequest req) throws ServiceException;
/**
*
* Parses a RFC 1867 compliant
* multipart/form-data
stream.
*
*
* @param req The servlet request to be parsed.
* @param path The location where the files should be stored.
* @return List of FileItem parts
* @throws ServiceException Problems reading/parsing the request or storing
* the uploaded file(s).
*/
List parseRequest(HttpServletRequest req, String path) throws ServiceException;
/**
*
* Parses a RFC 1867 compliant
* multipart/form-data
stream.
*
*
* @param req The servlet request to be parsed.
* @param sizeThreshold the max size in bytes to be stored in memory
* @param sizeMax the maximum allowed upload size in bytes
* @param path The location where the files should be stored.
* @return List of FileItem parts
* @throws ServiceException Problems reading/parsing the request or storing
* the uploaded file(s).
*/
List parseRequest(HttpServletRequest req, int sizeThreshold, int sizeMax, String path)
throws ServiceException;
/**
* Processes an RFC 1867
* compliant multipart/form-data
stream.
*
* @param req The servlet request to be parsed.
*
* @return An iterator to instances of FileItemStream
parsed from
* the request, in the order that they were transmitted.
*
* @throws ServiceException if there are problems reading/parsing the request or
* storing files. This may also be a network error
* while communicating with the client or a problem
* while storing the uploaded content.
*/
FileItemInputIterator getItemIterator(HttpServletRequest req) throws ServiceException;
/**
*
* Retrieves the value of size.max
property of the
* {@link org.apache.fulcrum.upload.UploadService}.
*
* @return The maximum upload size.
*/
long getSizeMax();
/**
*
* Retrieves the value of size.threshold
property of
* {@link org.apache.fulcrum.upload.UploadService}.
*
* @return The threshold beyond which files are written directly to disk.
*/
long getSizeThreshold();
/**
*
* Retrieves the value of the repository
property of
* {@link org.apache.fulcrum.upload.UploadService}.
*
* @return The repository.
*/
String getRepository();
/**
*
* Retrieves the value of the headerEncoding
property of
* {@link org.apache.fulcrum.upload.UploadService}.
*
* @return Returns the headerEncoding.
*/
String getHeaderEncoding();
/**
* Utility method that determines whether the request contains multipart
* content.
*
* @param req The servlet request to be evaluated. Must be non-null.
*
* @return true
if the request is multipart; false
* otherwise.
*/
boolean isMultipart(HttpServletRequest req);
/**
* The maximum allowed size of a sinlge file upload
* @return the maximum size
*/
long getFileSizeMax();
}