net.sourceforge.stripes.action
Class StreamingResolution

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

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.
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.
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

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

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