com.bristle.javalib.net.http
Class MultiPartFormDataParamMap

java.lang.Object
  java.util.AbstractMap
      java.util.HashMap
          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.