By paulsen on May 06, 2007
I have received questions from several people about how to use the "FileStreamer" feature of JSFTemplating. So I thought a blog would be the best way to demonstrate how it works.
FileStreamer provides the ability for the FacesServlet to stream content to the client (i.e. web browser). If that sounds generic, it is because FileStreamer is very generic. It allows you to define a ContentSource that is capable of getting content from just about anywhere. You might choose to get content from a database, retrieve it via a web service, generate it in code, access it from the filesystem or the classpath, or just about anywhere else. The ContentSource interface allows you to specify the content and information about it so that appropriate http headers will be set, causing the client (browser) to treat it correctly (i.e. Content-type, Content-Disposition, etc.). In addition to this, FileStreamer works in the context of JSF, meaning you will have access to managed beans or anything you require from your JSF environment. (NOTE: FileStreamer actually provides a Context which interacts with its environment. This allows different Context implementations to be provided for different environments; Servlet and JSF Contexts are currently available, see: ServletStreamerContext and FacesStreamerContext).
Lets look at a couple of examples.
First you have to have your JSFTemplating evironment setup. Follow these instructions for this.
Next to configure FileStreamer for JSF, add the following to your web.xml file:
The context-param registers 2 ContentSources. The source to both of these is checked into JSFTemplating's demo application. You can browse that source online here. The servlet-mapping requires a prefix mapping and needs its own dedicated FacesServlet mapping. "/resource/\*" is the default, however, this can be configured, see RESOURCE_PREFIX for more info.
Let's take a look at the key part of the ExampleContentSource to see how it works.
The above ContentSource (ExampleContentSource) is very simple, it generates its content from a String (see green text above). The String is some text with the request path (which is the PATH_INFO of the request, in other words the part of the URL after the "/resource"). Notice I added some HTML tags to show how they're treated. The red text shows that the Content-type is being explicitly set to "text/plain". This should cause the browser not to parse any html (so we should see those <b> tags on the screen).
As you can see, this simple ContentSource produces plain text in the browser. You also see that the URL requires "contentSourceId=example". "example" comes from the "id" of ExampleContentSource.
Let's take a look at 1 more example ContentSource. We'll use the same URL, except we'll use the contentSourceId of "proxy" to target our other ContentSource. Below is the interesting part of the source code for ProxyContentSource.java:
Again we are creating an InputStream, however, this time we are getting it via a URL. This time instead of hard-coding the Content-type, we're setting the extension of the file so that it will be mapped to an appropriate Content-type. Here's the output for the same URL as before (except w/ our "proxy" contentSourceId):
In this example, the content is pulled from java.sun.com from the server (not the client), then streamed to the client. The appropriate Content-type of "image/gif" was sent to the browser so that it could treat the content correctly. If you run this example, try other urls and types of media (html, pdf, doc, etc.).
I hope this blog gives you an idea of how FileStreamer functionality is useful. Please leave a comment and let me know what you think! Below is one more section describing how to configure FileStreamer in a Servlet environment (doesn't need JSF):
That's it... the rest is the same as above. You can change the url mapping directly in the web.xml file in this case. Oh... and yes, you can use the same ContentSources in both environments!