uk.co.weft.maybeupload
Class MaybeUploadServlet

java.lang.Object
  extended byjavax.servlet.GenericServlet
      extended byjavax.servlet.http.HttpServlet
          extended byuk.co.weft.maybeupload.MaybeUploadServlet
All Implemented Interfaces:
java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig
Direct Known Subclasses:
SnoopServlet

public abstract class MaybeUploadServlet
extends javax.servlet.http.HttpServlet

A superclass for Servlets which may need to handle file upload. Sun's Servlet class does not transparently handle multipart/form-data requests and, indeed, makes it extremely difficult for application-layer classes to handle them. This class is written as a wrapper round Sun's Servlet class which makes multipart/form-data handling transparent.

This class (and consequently all servlets which are subclasses of this class) know about the following configuration parameters:

allow_overwrite
Boolean: whether or not to allow uploaded files to overwrite previously uploaded files with the same name. Default is we don't.
max_upload
Integer: maximum size in bytes of file to upload. Optional. Default is 524288.
save_uploaded
Boolean: whether or not to save uploaded files directly to disk. Optional. Default is we do. If we don't, the uploaded file will be returned as a java.io.ByteArrayInputStream by a call to MaybeUploadRequestWrapper.get()
silently_rename
Boolean: whether or not to rename files whose names collide with existing files in the upload directory. Default is we do. Note that if both allow_overwrite and silently_rename are false and a name collision occurs, we will throw an (@see UploadException).
upload_dir_path
String: A path to a directory in the server-side local file-system in which uploaded files can be saved. Optional. Defaults to /tmp
upload_dir_url
String: the path to my upload directory (work directory) within the document root of the web server, if it is within the document root of the web server, else null. For example, if uploadDirPath was "/home/httpd/htdocs/upload", and the document root of the Web server was /home/httpd/htdocs, then it would make sense to have uploadDirURL set to "/upload/"A Optional. No Default.
All parameters may be supplied either as context-params or as init-params; if both are supplied the servlet-specific init-param will override the context-param.

NOTE: This code relies heavily on the Tomcat reference implementation and is thus in part Copyright (c) 1999 The Apache Software Foundation. All rights reserved.

"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)."

Version:
$Revision: 1.13 $ This revision: $Author: simon $
   $Log: MaybeUploadServlet.java,v $
   Revision 1.13  2002/12/16 16:03:21  simon
   Copyright and ownership attribution changed to Simon Brooke.

   Revision 1.12  2001/04/24 15:55:58  simon
   Patch release incorporating Aaron Dunlop's ByteArrayInputStream stuff.

   Revision 1.11  2001/04/09 11:24:24  simon
   Made maxUpload a configurable parameter ('max_upload')

   Revision 1.10  2001/03/22 10:49:53  simon
   Allow parameters to be set from context-params, as well as from
   init-params

   Revision 1.9  2001/02/22 11:16:31  simon
   Corrected deprecated use of UnavailableException, seeing we're no
   longer going for Servlet 2.1 spec backwards compatibility.

   Revision 1.8  2001/02/22 11:11:22  simon
   Moved project version symbol from Makefile to Make-local-dependencies;
   backed out changes in MaybeUploadServlet and
   uk/co/weft/maybeupload/Makefile made whilst investigating possibility
   of Servlet 2.1 spec compatibility.

   Revision 1.7  2001/01/23 19:12:17  simon
   A number of bugfixes, plus an important new feature: you can decide
   whether to allow name collisions in the upload directory to result
   in overwriting, renaming of the new file, or an exception.

   Revision 1.6  2001/01/22 15:09:53  simon
   Cache file object for upload directory at load time; provided public
   methods to access upload directory and upload directory URL

   Revision 1.5  2001/01/20 15:15:47  simon
   Added new configuration parameter, upload_dir_url, for use where the
   upload directory is visible within the HTTP space and may be linked
   to. Obviously this is optional; there may be many situations where you
   explicitly don't want anyone to be able to access uploaded files via
   HTTP!

   Revision 1.4  2001/01/17 16:14:50  simon
   Some tidying up of indentation whilst trying to track down bug - which
   turned out to be in htform.Servlet, not here.

   Revision 1.3  2001/01/09 12:14:12  simon
   Now tested with:
   	Netscape Communicator 4.76/Linux 2.2
   	Konqueror 1.9.8/Linux 2.2
   	Microsoft Internet Explorer 5.00.2014.0216IC
   File upload (including binary file upload) works. Remaining known bug:
   all fields must have data...

   Revision 1.2  2001/01/08 12:40:10  simon
   Now working; still tidying up

   Revision 1.1.1.1  2001/01/05 14:58:09  simon
   First cut - not yet tested

   
Author:
Simon Brooke (simon@jasmine.org.uk)
See Also:
Serialized Form

Field Summary
protected  boolean allowOverwrite
          whether to allow uploaded files to be overwritten when new files are uploaded; default is we don't
protected  int maxUpload
          the maximum upload size: by default, half a megabyte.
protected  boolean saveUploadedFilesToDisk
          whether or not to save uploads directly to disk; default is we do
protected  boolean silentlyRename
          whether or not to rename uploaded files to prevent name collisions; default is we do
protected  java.io.File uploadDir
          the actual upload directory as a file object
protected  java.lang.String uploadDirPath
          file system local path to where I unpack files I have uploaded
protected  java.lang.String uploadDirURL
          the path to my upload directory (work directory) within the document root of the web server, if it is within the document root of the web server, else null.
 
Constructor Summary
MaybeUploadServlet()
           
 
Method Summary
protected  void doDelete(MaybeUploadRequestWrapper req, javax.servlet.http.HttpServletResponse resp)
          Simple wrapper round HttpServlet.doDelete( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.
protected  void doGet(MaybeUploadRequestWrapper req, javax.servlet.http.HttpServletResponse resp)
          Simple wrapper round HttpServlet.doGet( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.
protected  void doHead(MaybeUploadRequestWrapper req, javax.servlet.http.HttpServletResponse resp)
          doHead is a bit more tricky.
protected  void doOptions(MaybeUploadRequestWrapper req, javax.servlet.http.HttpServletResponse resp)
          Simple wrapper round HttpServlet.doOptions( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.
protected  void doPost(MaybeUploadRequestWrapper req, javax.servlet.http.HttpServletResponse resp)
          Simple wrapper round HttpServlet.doPost( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.
protected  void doPut(MaybeUploadRequestWrapper req, javax.servlet.http.HttpServletResponse resp)
          Simple wrapper round HttpServlet.doPut( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.
protected  void doTrace(MaybeUploadRequestWrapper req, javax.servlet.http.HttpServletResponse resp)
          Simple wrapper round HttpServlet.doTrace( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.
 java.io.File getUploadDir()
           
 java.lang.String getUploadURL()
           
 void init(javax.servlet.ServletConfig config)
           
 void service(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Service a request.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

uploadDirPath

protected java.lang.String uploadDirPath
file system local path to where I unpack files I have uploaded


uploadDirURL

protected java.lang.String uploadDirURL
the path to my upload directory (work directory) within the document root of the web server, if it is within the document root of the web server, else null. For example, if uploadDirPath was "/home/httpd/htdocs/upload", and the document root of the Web server was /home/httpd/htdocs, then it would make sense to have uploadDirURL set to "/upload/"


allowOverwrite

protected boolean allowOverwrite
whether to allow uploaded files to be overwritten when new files are uploaded; default is we don't


silentlyRename

protected boolean silentlyRename
whether or not to rename uploaded files to prevent name collisions; default is we do


maxUpload

protected int maxUpload
the maximum upload size: by default, half a megabyte.


uploadDir

protected java.io.File uploadDir
the actual upload directory as a file object


saveUploadedFilesToDisk

protected boolean saveUploadedFilesToDisk
whether or not to save uploads directly to disk; default is we do

Constructor Detail

MaybeUploadServlet

public MaybeUploadServlet()
Method Detail

init

public void init(javax.servlet.ServletConfig config)
          throws javax.servlet.ServletException
Throws:
javax.servlet.ServletException

service

public void service(javax.servlet.http.HttpServletRequest req,
                    javax.servlet.http.HttpServletResponse resp)
             throws javax.servlet.ServletException,
                    java.io.IOException
Service a request. This method heavily dependent on the reference implementation.

Parameters:
req - the request to be serviced
resp - the response being constructed to this request
Throws:
javax.servlet.ServletException
java.io.IOException

doGet

protected void doGet(MaybeUploadRequestWrapper req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.IOException
Simple wrapper round HttpServlet.doGet( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.

Parameters:
req - a request wrapper which know how to handle upload
resp - a standard servlet response
Throws:
javax.servlet.ServletException
java.io.IOException

doPost

protected void doPost(MaybeUploadRequestWrapper req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      java.io.IOException
Simple wrapper round HttpServlet.doPost( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.

Parameters:
req - a request wrapper which know how to handle upload
resp - a standard servlet response
Throws:
javax.servlet.ServletException
java.io.IOException

doDelete

protected void doDelete(MaybeUploadRequestWrapper req,
                        javax.servlet.http.HttpServletResponse resp)
                 throws javax.servlet.ServletException,
                        java.io.IOException
Simple wrapper round HttpServlet.doDelete( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.

Parameters:
req - a request wrapper which know how to handle upload
resp - a standard servlet response
Throws:
javax.servlet.ServletException
java.io.IOException

doPut

protected void doPut(MaybeUploadRequestWrapper req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.IOException
Simple wrapper round HttpServlet.doPut( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.

Parameters:
req - a request wrapper which know how to handle upload
resp - a standard servlet response
Throws:
javax.servlet.ServletException
java.io.IOException

doOptions

protected void doOptions(MaybeUploadRequestWrapper req,
                         javax.servlet.http.HttpServletResponse resp)
                  throws javax.servlet.ServletException,
                         java.io.IOException
Simple wrapper round HttpServlet.doOptions( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.

Parameters:
req - a request wrapper which know how to handle upload
resp - a standard servlet response
Throws:
javax.servlet.ServletException
java.io.IOException

doTrace

protected void doTrace(MaybeUploadRequestWrapper req,
                       javax.servlet.http.HttpServletResponse resp)
                throws javax.servlet.ServletException,
                       java.io.IOException
Simple wrapper round HttpServlet.doTrace( ), so that you can depend on having a MaybeUploadRequestWrapper in your code.

Parameters:
req - a request wrapper which know how to handle upload
resp - a standard servlet response
Throws:
javax.servlet.ServletException
java.io.IOException

doHead

protected void doHead(MaybeUploadRequestWrapper req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      java.io.IOException
doHead is a bit more tricky. not really handled in this version, although I'll happily integrate code from anyone else who is sufficiently confident to write an implementation. Could just copy the HttpServlet version, but...

Parameters:
req - a request wrapper which know how to handle upload
resp - a standard servlet response
Throws:
javax.servlet.ServletException
java.io.IOException

getUploadDir

public java.io.File getUploadDir()
Returns:
my upload directory. Note that the upload directory cannot be set dynamically at run-time for security reasons

getUploadURL

public java.lang.String getUploadURL()
Returns:
as a String, the base URL for my upload directory if any. If returned, may be an absolute URL or a URL fragment relative to the document root of the HTTP server hosting the Servlet engine. In null, means that you cannot access the upload directory via HTTP