com.bristle.javalib.net.http
Class MultiPartFormDataParamMap

java.lang.Object
  extended by java.util.AbstractMap
      extended by java.util.HashMap
          extended by com.bristle.javalib.net.http.MultiPartFormDataParamMap
All Implemented Interfaces:
Serializable, Cloneable, Map

public class MultiPartFormDataParamMap
extends HashMap

This class makes the form parameters from an HTML form with enctype='multipart/form-data' available as a simple map, like the map returned by ServletRequest.getParameterMap() for other HTML forms. It can also be used with regular HTML forms, but it offers no advantages in that case, because it simply returns the map returned by ServletRequest.getParameterMap().
It handles regular form parameters differently than streamed file parameters (the kind generated by the HTML INPUT tag with TYPE='FILE'). Regular form parameters are added to the map, and can be accessed at any time, in the usual fashion. However, streamed files are not added to the map. Instead, they are passed as FileItemStreams to the specified callback method (if any) as they are discovered during the iteration over the incoming HTTP request stream. Such files must be fully processed during the callback, because they become unavailable as soon as the iteration resumes. This is because they are really just part of the larger HTTP request stream. Attempts to access the FileItemStream after the callback completes throw the exception: FileItemStream.ItemSkippedException

Usage:

   - The typical scenario for using this class from Java code is:
     - Call parseRequestStream(HttpServletRequest,FileItemStreamCallBack) 
       or parseRequestStream(HttpServletRequest), passing an HTTP 
       request and an optional callback.  This parses the request, and calls 
       the callback (if any) for each file (if any) in the streamed HTTP 
       request:
           import org.apache.commons.fileupload.FileItemStream;
           class MyCallback 
                   implements MultiPartFormDataParamMap.FileItemStreamCallBack
           {
               public void fullyProcessAFileItemStream
                                   (FileItemStream fileItemStream) 
                                    throws Exception
               {
                   String strFieldName   = fileItemStream.getFieldName());
                   String strFileName    = fileItemStream.getName();
                   String strContentType = fileItemStream.getContentType();
                   InputStream streamIn  = fileItemStream.openStream();
                   processTheStreamSavingToDiskOrWhatever(streamIn);
               }
           }
           ...
           MultiPartFormDataParamMap formParams 
                               = new MultiPartFormDataParamMap();
           formParams.parseRequestStream(request, new MyCallback());
     - Access the param map as you would ordinarily access the map returned
       by ServletRequest.getParameterMap():
           formParams.containsKey("param1")
           formParams.containsKey(strParam)
           formParams.get("param1")
           formParams.get(strParam)
           etc.
     - For form parameters that occur earlier in the HTTP request stream 
       than a file, you can access the formParams map during the callback
       for that file as well as after it.  For form parameters that occur 
       later in the stream, the parameters will not yet be in the map.

   - The typical scenario for using this class from JSP code is:
     - Call parseRequestStream(HttpServletRequest,FileItemStreamCallBack) 
       or parseRequestStream(HttpServletRequest) from Java code, 
       exactly as above.
     - Add the map to the context for convenient access from EL expressions:
           <%
           pageContext.setAttribute("formParams", formParams);
           %>
     - Access the non-file params in the formParams map via EL:
           ${formParams.param1}
           ${formParams["param1"]}
           ${formParams[strParam]}

Assumptions:
Effects:
       - None.
Anticipated Changes:
Notes:
Implementation Notes:
Portability Issues:
Revision History:
   $Log$

See Also:
Serialized Form

Nested Class Summary
static interface MultiPartFormDataParamMap.FileItemStreamCallBack
          This interface must be implemented by any class that expects to be called as a callback by parseRequestStream(HttpServletRequest, FileItemStreamCallBack).
 
Constructor Summary
MultiPartFormDataParamMap()
           
 
Method Summary
 void parseRequestStream(HttpServletRequest request)
          Parse the specified HTTP request, initializing the map.
 void parseRequestStream(HttpServletRequest request, MultiPartFormDataParamMap.FileItemStreamCallBack callback)
          Parse the specified HTTP request, initializing the map, and calling the specified callback (if not null) for each file (if any) in the streamed HTTP request.
 
Methods inherited from class java.util.HashMap
clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, put, putAll, remove, size, values
 
Methods inherited from class java.util.AbstractMap
equals, hashCode, toString
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Constructor Detail

MultiPartFormDataParamMap

public MultiPartFormDataParamMap()
Method Detail

parseRequestStream

public void parseRequestStream(HttpServletRequest request,
                               MultiPartFormDataParamMap.FileItemStreamCallBack callback)
                        throws FileUploadException,
                               IOException,
                               Throwable
Parse the specified HTTP request, initializing the map, and calling the specified callback (if not null) for each file (if any) in the streamed HTTP request.

Parameters:
request - The HTTP request
callback - The callback class
Throws:
FileUploadException - When the request is badly formed.
IOException - When an I/O error occurs reading the request.
Throwable - When thrown by the callback.

parseRequestStream

public void parseRequestStream(HttpServletRequest request)
                        throws FileUploadException,
                               IOException
Parse the specified HTTP request, initializing the map.

Parameters:
request - The HTTP request
Throws:
FileUploadException - When the request is badly formed.
IOException - When an I/O error occurs reading the request.