public interface ServletRequest 
{
    /**
     * Get the request body content as an Object. 
     * 
     * <p>The bytes received byte the server will be parsed and converted to the Object
     * by a {@link RequestContentConverter} provided either by the container or the 
     * application and configured in the deployment descriptor or servlet annotations. 
     * Examples of the type of Object that could be returned include 
     * {@link java.nio.ByteBuffer}, {@link String}, {@link java.io.File} and 
     * {@link org.w3c.dom.Document}. If the request specifies a character encoding or 
     * Locale, then this will be used for the parsing of the content, otherwise default 
     * encodings may be specified in the deployment descriptor or servlet annotations.
     * </p>
     * 
     * <p>If the deployment descriptor or servlet annotations indicates that the request 
     * URL is asynchronous, then the container will parse the content before the request 
     * is dispatched to the filter chain and/or servlet and this call will never block. 
     * Otherwise, the content is parsed during this call and may block waiting for the 
     * complete content to be received.</p>
     * 
     * @return   an object containing parsed body of the request
     *
     * @exception IllegalStateException  if the {@link #getReader} or 
     *     {@link #getInputStream} methods has already been called for this request
     *                                   
     * @exception ObjectSTreamException  if there was a problem parsing the content.                                
     *
     * @exception IOException           if an input or output exception occurred
     */
    Object getContent() throws IllegalStateException, ObjectStreamException;
   
}

public interface ServletResponse
{
    // existing response methods omitted

    /**
     * Set the response content body
     * 
     * <p>Set the response body to be sent as an Object.  The Object will be
     * converted to bytes byte a {@link ResponseContentConverter} instance 
     * provided either by the container or application and configured in the
     * deployment descriptor or servlet annotations.</p>
     * 
     * <p>The converter will set the content length, content type and content
     * encoding of the response.</p>
     * 
     * <p>A call to {@link #flushBuffer()} will block until the entire content
     * is converted to bytes and flushed. If {@link #flushBuffer()} is not called,
     * then the container may generate and write the byte content asynchronously 
     * after the call to the filter chain and servlet service method return 
     * to the container.
     * 
     * @exception IllegalStateException if any of the {@link #getWriter()}, 
     *     {@link #getNonStopWriter(),  {@link #getOutputStream()} or
     *     {@link #getNonStopOutputStream()} methods have been called on 
     *     this response
     *
     */
    void setContent(Object content);    
}

/**
 * A handler for Request content.
 * 
 * <p>Implementations of this interface are responsible for handling 
 * bytes received from a request, normally by conversion to an Object instance that will be 
 * made available via the {@link ServletRequest#getContent()} method.
 * 
 * <p>The container will create as many instances of a converter as needed
 * and an instance will be associated with a request by a call to 
 * {@link #init(ServletRequest)}. The container will call 
 * {@link #convert(byte[])} as content is received until either an object 
 * is returned or an exception is throw.
 * 
 * <p>Container provided handlers are not required to implement this
 * interface.
 * 
 */
public interface RequestContentHandler
{
    interface Dispatcher
    {
        /**
         * Dispatch the request to a Servlet.
         * <p> The request that was passed to 
         * {@link RequestContentHandler#begin(Dispatcher,ServletRequest)} will be
         * dispatched to a Servlet, potentially via a Filter chain. The content 
         * object passed will be available via the {@link ServletRequest#getContent()} method.
         * Any content bytes not consumed asynchronously will be available via the normal 
         * blocking API of the request.
         */
        void dispatch(Object content);
    }

    /**
     * Initialize this handler for the request.
     * <p>
     * @param dispatcher The dispatcher instance that should be used to 
     * call {@link Dispatcher#dispatch} when the content is converted to
     * an Object. The request will not be dispatched to a servlet until 
     * dispatch is called.
     * @param request The request that contains the content. The request 
     * headers may be inspected, but not methods that consume content may
     * be called (eg {@link ServletRequest#getInputStream()}. 
     * @param response The response.
     * @throws IllegalStateException If this converter cannot convert the
     * request.
     */
    void begin(Dispatcher dispatcher, ServletRequest request, ServletResponse response);
    
    
    /**
     * handle a chunk of request content.
     * 
     * <p>This method is called when the container receives some bytes of 
     * content. The content may not be complete and subsequent calls to
     * convert will be required to deliver the complete content.
     * A subsequent call will not be made until after the current call
     * to handle has returned. Bytes not consumed by a call to handle will
     * be included in the next call to handle.
     * 
     * @param chunk Either a partial or complete content as an
     * array of bytes.
     * @param offset the offset into the chunk array where content starts
     * @param length the length of the content withing the array
     * @return The number of bytes consumed by this call.
     * @throws IOException If the content cannot be parsed.
     */
    int handle(byte[] chunk,int offset,int length) throws IOException;

    /**
     * handle a read error.
     *
     * <p> This method is called when the container detects an error on a 
     * connection that is delivering content.
     * After this call, this instance of the handler is no longer associated
     * with the request passed in begin and may be reused for a new request.
     * @param th a Throwable indicating the error condition.
     */
    void error(Throwable th);

    /**
     * handle a timeout.
     *
     * <p> This method is called when the container detects no activity on
     * a connection that is delivering content.
     * After this call, this instance of the handler is no longer associated
     * with the request passed in begin and may be reused for a new request.
     */
    void timeout();

    /**
     * Complete the request
     *
     * <p> This method is called when the container detects the end of 
     * request content. 
     * After this call, this instance of the handler is no longer associated
     * with the request passed in begin and may be reused for a new request.
     *
    void complete();
    
}

/* ------------------------------------------------------------ */
/**
 * A handler for Response content.
 * 
 * <p>Implementations of this interface are responsible for converting 
 * Objects passed in the {@link ServletResponse#setContent(Object)} method 
 * to bytes to be sent as the response content.
 * 
 * <p>The container will create as many instances of a converter as needed
 * and an instance will be associated with a response by a call to 
 * {@link #init(ServletResponse)}. The container will call 
 * {@link #convert(byte[], int, int)} until -1 is returned.
 * 
 * <p>Container provided converters are not required to implement this
 * interface.
 *
 */
public interface ResponseContentHandler
{
    /**
     * Associate this handler with a response.
     * <p>The response headers may be set to indicate the content
     * size, type and encoding.
     * 
     * @param response The response
     * @param content The content to convert.
     * @throws IllegalStateException If the content cannot be converted
     * by this converter.
     */
    void begin(HttpServletResponse response, Object content);

    /** 
     * Convert the content to bytes. The converted bytes are written into
     * the passed buffer starting at the given offset and not exceeding the
     * given length. The actual number of bytes written is returned.
     * The bytes written my represent all of the content or a part of the
     * content. Subsequent calls to convert may be required to convert the
     * entire content.
     * 
     * <p>The container will not call convert until a previous call to convert 
     * returns. The container may delay calling convert until it is ready to
     * send more content to the client.
     * 
     * @param buffer The byte array into which content should be written
     * @param offset The offset into the array at which content should be written
     * @param length The maximum number of bytes that may be written.
     * @return The number of bytes written or -1 to indicate that the entire
     * content has been written.
     * @throws IOException If the content cannot be converted.
     */
    int handle(byte[] buffer,int offset, int length) throws IOException;
}

<request-content-handler>    
  <url-pattern>/comet/*</url-pattern>

  <mime-type>text/json</mime-type>
  <content-class>java.util.Map</content-class>
  <asynchronous/>
  <provided/>
  <handler-class>com.acme.ajax.JsonContentParser</handler-class>
</request-content-handler>

<response-content-handler>
  <url-pattern>/comet/*</url-pattern>

  <content-class>org.w3c.dom.Document</content-class>
  <content-type>text/xml; charset=utf-8</content-type>
  <provided/>
</request-content-handler>

<%@ page contentType='text/html; charset=UTF-8' import='java.util.Map,java.io.File' %>
<%
Map content=(Map)request.getContent();
if (content==null)
{
%>
    <h2>UPLOAD content</h2>
    <form method='POST' enctype='multipart/form-data' accept-charset='utf-8' action=".">
      Description: <input type='text' name='comment' value='comment'/><br/>
      File: <input type='file' name='file' /><br/>
      <input type='submit' name='Action' value='Submit'><br/>
    </form>
<%
}
else
{
    String comment = (String)content.get("comment");
    File file = (File)content.get("file");
    String path="/store/"+file.getName();
    file.renameTo(new File(request.getRealPath(path)));
%>
    <h2>UPLOADED content</h2>
    Comment: <%= comment%><br/>
    File: <a href="<%=path%>"><%=file.getName()%></a><br/>  
<%
}
%>

<request-content-handler>    
  <url-pattern>/upload.jsp</url-pattern>

  <mime-type>multipart/form-data</mime-type>
  <content-class>java.util.Map</content-class>
  <asynchronous/>
  <provided/>
</request-content-handler>