any

byte[]

any

java.lang.String

any

java.io.File

text/xml

org.w3c.dom.Document

text/json

java.util.Map

multipart/form-data

java.util.Map

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;

    /**
     * Suspend the processing of the request and associated {@link ServletResponse}.
     * 
     * <p>After this method has been called, the lifecycle of the request will be 
     * extended beyond the return to the container from the 
     * {@link Servlet#service(ServletRequest, ServletResponse)}  method and 
     * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} calls. If a 
     * request is suspended, then the container will not commit the associated response 
     * when the call to the filter chain and/or servlet service method returns to the 
     * container. Instead the container will wait until either 
     * {@link ServletRequest#resume()}  is called or the passed timeout expires, at
     * which  time the request will be redispatched via the normal filter chain to the
     * servlet.
     * </p>
     * 
     * <p>The associated {@link ServletResponse} object is disabled by this call, so 
     * that all calls to modify or generate a response are silently ignored, until 
     * such time as the request is retried. With the exception that the objects 
     * returned by {@link ServletResponse#getNonStopOutputStream()} and  
     * {@link ServletResponse#getNonStopWriter} remain active throughout the request 
     * lifecycle.</p>
     * 
     * <p>If a request is already suspended, any subsequent calls to suspend will set
     * the timeout to the minimum of the previous timeout and the newly passed 
     * timeout</p>
     * 
     * <p>Suspend may only be called by a thread that is within the service calling 
     * stack of {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
     * and/or {@link Servlet#service(ServletRequest, ServletResponse)}</p>
     * 
     * @see {@link #resume()}
     * 
     * @param timeoutMs The time in milliseconds to wait before retrying this request.
     * 
     * @exception IllegalStateException If the calling thread is not within the calling 
     * stack of  {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
     * and/or {@link Servlet#service(ServletRequest, ServletResponse)}
     */
    void suspend(long timeoutMs);

    
    /**
     * Resume a suspended request.
     * 
     * <p>This method can be called by any thread that has been passed a reference to 
     * the request to request that the request be redispatched</p>
     * 
     * <p>If resume is called before a suspended request is returned to the container 
     * (ie the thread that called {@link #suspend(long)} is still within the filter
     * chain and/or servlet service method), then the resume does not take effect until
     * the call to the filter chain and/or servlet returns to the container. In this 
     * case, until  the service call returns, both {@link #isSuspended()} and 
     * {@link isResumed()} to return true.</p>
     * 
     * <p>If resume is called on an unsuspended request, then the resume will apply to 
     * any subsequent calls to suspend. In this case, {@link #isResumed()} will true 
     * and {@link #isSuspended()} will return false. </p>
     * 
     * <p>If resume is called on a request after the request lifecycle is complete, 
     * then the results are undefined</p>
     * 
     * <p>Multiple calls to resume are ignored</p>
     * 
     * @see {@link #response()}
     * 
     */
    void resume();

    /**
     * @return true after {@link #suspend(long)} has been called and before the request 
     * has been resumed or timedout.
     */
    boolean isSuspended();

    /**
     * @return true after {@link #resume()} has been called and before any subsequent
     * call to suspend
     */
    boolean isResumed();

    /**
     * @return true after a request has been retried as the result of a resume or a 
     * timeout
     */
    boolean isRetry();

    /**
     * @return true after a request has been retried as the result of a timeout
     */
    boolean isTimeout();
}

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);

    /**
     * Returns a {@link PrintWriter} suitable for writing character text
     * in the response.  Unlike the writer returned by {@link #getWriter()},
     * the writer returned by this method is not affected by a call to 
     * {@link ServletRequest#suspend(long)} and may be used by any thread
     * during the request lifecycle. </p>
     * 
     * <p>The writer is not guaranteed to be thread safe, and if multiple 
     * threads are using the stream, they must use some form of mutual
     * exclusion.</p>
     *
     * <p>Calling flush() on the Writer commits the response.</p>
     *
     * @return a {@link ServletOutputStream} for writing binary data   
     *
     * @exception IllegalStateException if any of the {@link #getWriter()}, 
     *     {@link #getNonStopWriter() or {@link #setContent(Object)} methods
     *     have been called on this response
     *     
     * @exception UnsupportedEncodingException
     *                  if the character encoding returned
     *                  by <code>getCharacterEncoding</code> cannot be used
     *
     *
     */
    PrintWriter getNonStopWriter();

    /**
     *
     * Returns a {@link ServletOutputStream} suitable for writing binary 
     * data in the response. The servlet container does not encode the
     * binary data.   Unlike the stream returned by {@link #getOutputStream()},
     * the stream returned by this method is not affected by a call to 
     * {@link ServletRequest#suspend(long)} and may be used by any thread
     * during the request lifecycle. </p>
     * 
     * <p>The stream is not guaranteed to be thread safe, and if multiple 
     * threads are using the stream, they must use some form of mutual
     * exclusion.</p>
     *
     * <p>Calling flush() on the ServletOutputStream commits the response.</p>
     *
     *
     * @return a {@link ServletOutputStream} for writing binary data   
     *
     * @exception IllegalStateException if any of the {@link #getWriter()}, 
     *     {@link #getNonStopWriter() or {@link #setContent(Object)} methods
     *     have been called on this response
     *
     * @exception IOException   if an input or output exception occurred
     *
     */
    ServletOutputStream getNonStopOutputStream();
    
}

/**
 * A converter for Request content.
 * 
 * <p>Implementations of this interface are responsible for converting 
 * bytes received from a request to and 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 converters are not required to implement this
 * interface.
 * 
 */
public interface RequestContentConverter
{
    
    /**
     * Initialize this converter for the request.
     * @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()}. 
     * @throws IllegalStateException If this converter cannot convert the
     * request.
     */
    void init(ServletRequest request);
    
    
    /**
     * Convert a bytes of 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 convert has returned.
     * 
     * @param chunk Either a partial or complete content as an
     * array of bytes.
     * @return The converted object or null if more content is required.
     * @throws IOException If the content cannot be parsed.
     */
    Object convert(byte[] chunk) throws IOException;
    
}

/* ------------------------------------------------------------ */
/**
 * A converter 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 ResponseContentConverter
{
    /**
     * Associate this converter 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 init(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 convert(byte[] buffer,int offset, int length) throws IOException;
}

<request-converter>    
  <url-pattern>/comet/*</url-pattern>

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

<response-converter>
  <url-pattern>/comet/*</url-pattern>

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

<%@ 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='TextField' value='comment'/><br/>
      File: <input type='file' name='file' /><br/>
      <input type='submit' name='Action' value='Submit'><br/>
    </form>
<%
}
else
{
    String description = (String)content.get("description");
    File file = (File)content.get("file");
    String path="/store/"+file.getName();
    file.renameTo(new File(request.getRealPath(path)));
%>
    <h2>UPLOADED content</h2>
    Description: <%= description%><br/>
    File: <a href="<%=path%>"><%=file.getName()%></a><br/>  
<%
}
%>