net.sourceforge.stripes.action
Class StreamingResolution

java.lang.Object
  extended by net.sourceforge.stripes.action.StreamingResolution
All Implemented Interfaces:
Resolution

public class StreamingResolution
extends Object
implements Resolution

Resolution for streaming data back to the client (in place of forwarding the user to another page). Designed to be used for streaming non-page data such as generated images/charts and XML islands.

Optionally supports the use of a file name which, if set, will cause a Content-Disposition header to be written to the output, resulting in a "Save As" type dialog box appearing in the user's browser. If you do not wish to supply a file name, but wish to achieve this behaviour, simple supply a file name of "".

StreamingResolution is designed to be subclassed where necessary to provide streaming output where the data being streamed is not contained in an InputStream or Reader. This would normally be done using an anonymous inner class as follows:

return new StreamingResolution("text/xml") {
    public void stream(HttpServletResponse response) throws Exception {
        // custom output generation code
        response.getWriter().write(...);
        // or
        response.getOutputStream().write(...);
    }
}.setFilename("your-filename.xml");

Author:
Tim Fennell

Constructor Summary
StreamingResolution(String contentType)
          Constructor only to be used when subclassing the StreamingResolution (usually using an anonymous inner class.
StreamingResolution(String contentType, InputStream inputStream)
          Constructor that builds a StreamingResolution that will stream binary data back to the client and identify the data as being of the specified content type.
StreamingResolution(String contentType, Reader reader)
          Constructor that builds a StreamingResolution that will stream character data back to the client and identify the data as being of the specified content type.
StreamingResolution(String contentType, String output)
          Constructor that builds a StreamingResolution that will stream character data from a String back to the client and identify the data as being of the specified content type.
 
Method Summary
protected  void applyHeaders(HttpServletResponse response)
          Sets the response headers, based on what is known about the file or stream being handled.
 void execute(HttpServletRequest request, HttpServletResponse response)
          Streams data from the InputStream or Reader to the response's OutputStream or PrinterWriter, using a moderately sized buffer to ensure that the operation is reasonable efficient.
 StreamingResolution setAttachment(boolean attachment)
          Indicates whether to use content-disposition attachment headers or not.
 void setCharacterEncoding(String characterEncoding)
          Sets the character encoding that will be set on the request when executing this resolution.
 StreamingResolution setFilename(String filename)
          Sets the filename that will be the default name suggested when the user is prompted to save the file/stream being sent back.
 StreamingResolution setLastModified(long lastModified)
          Sets the modification-date timestamp.
 StreamingResolution setLength(long length)
          Sets the file length.
protected  void stream(HttpServletResponse response)
           Does the actual streaming of data through the response.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StreamingResolution

public StreamingResolution(String contentType)
Constructor only to be used when subclassing the StreamingResolution (usually using an anonymous inner class. If this constructor is used, and stream() is not overridden then an exception will be thrown!

Parameters:
contentType - the content type of the data in the stream (e.g. image/png)

StreamingResolution

public StreamingResolution(String contentType,
                           InputStream inputStream)
Constructor that builds a StreamingResolution that will stream binary data back to the client and identify the data as being of the specified content type.

Parameters:
contentType - the content type of the data in the stream (e.g. image/png)
inputStream - an InputStream from which to read the data to return to the client

StreamingResolution

public StreamingResolution(String contentType,
                           Reader reader)
Constructor that builds a StreamingResolution that will stream character data back to the client and identify the data as being of the specified content type.

Parameters:
contentType - the content type of the data in the stream (e.g. text/xml)
reader - a Reader from which to read the character data to return to the client

StreamingResolution

public StreamingResolution(String contentType,
                           String output)
Constructor that builds a StreamingResolution that will stream character data from a String back to the client and identify the data as being of the specified content type.

Parameters:
contentType - the content type of the data in the stream (e.g. text/xml)
output - a String to stream back to the client
Method Detail

setFilename

public StreamingResolution setFilename(String filename)
Sets the filename that will be the default name suggested when the user is prompted to save the file/stream being sent back. If the stream is not for saving by the user (i.e. it should be displayed or used by the browser) this value should not be set.

Parameters:
filename - the default filename the user will see
Returns:
StreamingResolution so that this method call can be chained to the constructor and returned

setCharacterEncoding

public void setCharacterEncoding(String characterEncoding)
Sets the character encoding that will be set on the request when executing this resolution. If none is set, then the current character encoding (either the one selected by the LocalePicker or the container default one) will be used.

Parameters:
characterEncoding - the character encoding to use instead of the default

setLastModified

public StreamingResolution setLastModified(long lastModified)
Sets the modification-date timestamp. If this property is set, the browser may be able to apply it to the downloaded file. If this property is unset, the modification-date parameter will be omitted.

Parameters:
lastModified - The date-time (as a long) that the file was last modified. Optional.
Returns:
StreamingResolution so that this method call can be chained to the constructor and returned.

setLength

public StreamingResolution setLength(long length)
Sets the file length. If this property is set, the file size will be reported in the HTTP header. This may help with file download progress indicators. If this property is unset, the size parameter will be omitted.

Parameters:
length - The length of the file in bytes.
Returns:
StreamingResolution so that this method call can be chained to the constructor and returned.

setAttachment

public StreamingResolution setAttachment(boolean attachment)
Indicates whether to use content-disposition attachment headers or not. (Defaults to true).

Parameters:
attachment - Whether the content should be treated as an attachment, or a direct download.
Returns:
StreamingResolution so that this method call can be chained to the constructor and returned.

execute

public final void execute(HttpServletRequest request,
                          HttpServletResponse response)
                   throws Exception
Streams data from the InputStream or Reader to the response's OutputStream or PrinterWriter, using a moderately sized buffer to ensure that the operation is reasonable efficient. Once the InputStream or Reader signaled the end of the stream, close() is called on it.

Specified by:
execute in interface Resolution
Parameters:
request - the HttpServletRequest being processed
response - the paired HttpServletResponse
Throws:
IOException - if there is a problem accessing one of the streams or reader/writer objects used.
Exception - exceptions of any type may be thrown if the Resolution cannot be executed as intended

applyHeaders

protected void applyHeaders(HttpServletResponse response)
Sets the response headers, based on what is known about the file or stream being handled.

Parameters:
response - the current HttpServletResponse

stream

protected void stream(HttpServletResponse response)
               throws Exception

Does the actual streaming of data through the response. If subclassed, this method should be overridden to stream back data other than data supplied by an InputStream or a Reader supplied to a constructor.

If an InputStream or Reader was supplied to a constructor, this implementation uses a moderately sized buffer to stream data from it to the response to make the operation reasonably efficient, and closes the InputStream or the Reader. If an IOException occurs when closing it, that exception will be logged as a warning, and not thrown to avoid masking a possibly previously thrown exception.

Parameters:
response - the HttpServletResponse from which either the output stream or writer can be obtained
Throws:
Exception - if any problems arise when streaming data


? Copyright 2005-2006, Stripes Development Team.