PrimeFaces 4.0 使用 <p:fileDownload> 标签实现文件下载

这两天在使用 primefaces 4.0 做壹個下载文件的功能，去官方网站 primefaces.org 看了下，只有壹個 PDF 版用户指南和各种用例的在线 Demo ，目前可以在官方网站上找到的下载案例见于 http://www.primefaces.org/showcase/ui/fileDownload.jsf，能够看到部分源代码，但是找不到整個工程，实在是很不方便。后来又通过 Google 搜索了下，终于让我在 http://networkedblogs.com/B8rUw 找到了 primefaces-showcase 源代码和 WAR 安装包的下载地址，原来是在 primefaces 自己的 repository 资源库里的，仔细看了下，是用标签 <p:fileDownload> 来实现的，具体的代码实现如下。

首先是 XHTML 页面，包含了三部分，壹個<h:form>表单，用于提交请求到后端服务器；壹個 <p:dialog>对话框，服务器响应请求之后，但是页面还没有弹出文件下载窗口这段时间里，在页面上显示壹個进度条窗口；最后壹部分是 javascript 脚本代码，用于控制上面的 <p:dialog>的显示与隐藏。

<p:dialog modal="true" widgetVar="statusDialog" header="Status" draggable="false" closable="false" resizable="false">
    <p:graphicImage value="/design/ajaxloadingbar.gif" />
</p:dialog>

<h:form id="form">
	<p:commandButton id="downloadLink" value="Download" ajax="false" onclick="PrimeFaces.monitorDownload(start, stop)" icon="ui-icon-arrowthichk-s">
		<p:fileDownload value="#{fileDownloadController.file}" />
	</p:commandButton>
</h:form>

<script type="text/javascript">
	function start() {
		PF('statusDialog').show();
	}

	function stop() {
		PF('statusDialog').hide();
	}
</script>

其中几個需要注意的地方是：1、<p:graphicImage>里的 value 属性指向了壹個 GIF 图片，这個图片实际放置在 WebRoot 的根目录下，也就是说，相对路径实际是 /WebRoot/design/ajaxloadingbar.gif ；2、在 <p:commandButton> 里有壹個 onclick 事件指向 PrimeFaces.monitorDownload(start, stop)，其实这里它指定了两個方法分别是 start() 和 stop()，具体它们的表现通过 Demo 的演示效果就可以看出来。

后台部分的代码主要是 FileDownloadController ，它的内容如下所示：

package org.primefaces.examples.view;

import java.io.InputStream;
import javax.faces.context.FacesContext;
import javax.servlet.ServletContext;

import org.primefaces.model.DefaultStreamedContent;
import org.primefaces.model.StreamedContent;

public class FileDownloadController {

	private StreamedContent file;
	
	public FileDownloadController() {
		ServletContext servletContext = (ServletContext)FacesContext.getCurrentInstance().getExternalContext().getContext();
        InputStream stream = servletContext.getResourceAsStream("/images/optimusprime.jpg");
		file = new DefaultStreamedContent(stream, "image/jpg", "downloaded_optimus.jpg");
	}

    public StreamedContent getFile() {
        return file;
    }  
}

上述代码则比较简单，没有什么好说的，唯壹的地方在于 getResourceAsStream() 方法的参数是壹個文件的相对路径，这個路径也是相对于 WebRoot 的，也就是说，真正的 optimusprime.jpg 图片是放置在 WebRoot 的 /WebRoot/images/optimusprime.jpg 目录下，这样 Controller 才能正确读取到这個图片。至于 DefaultStreamedContent 这個类，则是 primefaces 框架自己提供的壹個简单的获取 stream 输入流的实现类，它原本有四個构造方法（如下所示），但是我们这里只使用了第3种。

1、public DefaultStreamedContent(InputStream stream);
2、public DefaultStreamedContent(InputStream stream, String contentType);
3、public DefaultStreamedContent(InputStream stream, String contentType, String name);
4、public DefaultStreamedContent(InputStream stream, String contentType, String name, String contentEncoding);

参数说明：
1、stream：要下载的文件的输入流对象；
2、contentType：要下载的文件的文件类型，确切的说是mimeType，如MS EXCEL2003 的mimeType 是"application/vnd.ms-excel"，JPG图片的mimeType 是“<span></span>image/jpg”;
3、name：给下载的文件重新指定壹個文件名（包括扩展名），会显示在浏览器端的下载窗口中；
4、contentEncoding：文件的默认编码格式，如GBK、UTF-8、GB18030等，这個字段貌似用的稍少些；

按照这样的方式，我们就可以成功的实现文件下载功能了。另外，附壹张 primefaces-showcase 的 war 包解压之后的目录结构图。

最后我想吐槽下，Primefaces 网站上的超链接和菜单排列真有够乱的，顶上的几個链接我以为是带有下拉列表的，结果点击之后是直接全页面刷新并跳转的，真正的各种菜单链接其实是放在页面底部的黑色背景区域里的，花了我好长时间才找到。而且光是通过网站我们还不能直接找到 primefaces repository 的地址，只能找到它的在线 Demo，其中有很多小的细节通过 Demo 其实是看不出来的，最好的办法是结合完整的源代码进行学习。不知道 PrimeFaces 官方是怎么想的，把個网站建设的乱七八糟。
本文重点参考了如下内容：
[1]Download PrimeFaces ShowCase and Source Code http://networkedblogs.com/B8rUw
[2]What are the Microsoft Office MIME Types http://filext.com/faq/office_mime_types.php
[3]PrimeFaces Demo War 包下载地址（包含所有的样例代码） http://repository.primefaces.org/org/primefaces/prime-showcase/1.0.0-SNAPSHOT/prime-showcase-1.0.0-SNAPSHOT.war