ZK Component Reference/Essential Components/Filedownload

Fileupload

• Demonstration: File Downpload
• Java API: Filedownload
• JavaScript API: N/A
• Style Guide: N/A

Employment/Purpose

Filedownload provides provides a set of utilities to prompt a user for downloading a file from the server to the client.

Notice that Filedownload is not a component. Rather, it is a collection of utilities for file download.

Unlike the iframe component that displays the file in the browser window, a file download dialog is shown at the browser if one of the save methods is called. Then, the user can specify the location in his local file system to save the file.

<button label="Download">
	<attribute name="onClick">{
		java.io.InputStream is = desktop.getWebApp().getResourceAsStream("/test/download.html");
		if (is != null)
			Filedownload.save(is, "text/html", "download.html");
		else
			alert("/test/download.html not found");
	}
	</attribute>
</button>

Limitation of IE 6/7/8

With this approach, Internet Explorer 6, 7 and 8 will show up an warning message on top of the browser as shown below ("To help protect your security, Internet Explorer...").

If the user allows the download (right click and select Download File...), IE will eventually reload the page. It means the whole content of the page is reloaded and the downloading does not take place. And, the user have to click the download again. It is a tedious user experience.

To work around it, you usually have to prepare another page for real download, and then use FORM submit to redirect to the page for real download. For example,

<!-- the page that guides users to download -->
<h:form xmlns:h="native" action="real-download.zul" target="_blank">
	<button label="Download" type="submit"/>
</h:form>

And, the page for real download could be implemented in, say, JSP or a servlet by use of Https.write(HttpServletRequest, HttpServletResponse, Media, boolean, boolean). For example,

<%-- the page really downloads the file to response --%>

<%@ page import="org.zkoss.web.servlet.http.Https, org.zkoss.util.media.AMedia, java.io.*" %>
<%
	Https.write(request, response,
		new AMedia("B1896797.pdf", null, null,
			application.getResourceAsStream("/test2/B1896797.pdf")),
		true/*download*/, false);
%>
<blockquote>

----
<references/>
</blockquote>

= The Resumable Download =

{{ZK EE}}

In certain situations, you might prefer to generate an URL that can be used even if the desktop becomes invalid. For example, you want to allow users to use a download manager (such as <code>wget</code> and <code>DownThemAll</code>). Another example is related to the blocking feature found in some browsers -- which confirm the download with the user and causes the page to reload (and then the previous desktop is lost).

To solve this, you have to use the so-called resumable download. By resumable we mean the user can bookmark the URL and download it later (and even resume the download in the middle). On the other hand, the download URL of the <code>save</code> method becomes obsolete as soon as the desktop (or session) is gone.

To use resumable download, you have to invoke the <code>saveResumable</code> method of <javadoc>org.zkoss.zkmax.zul.Filedownload</javadoc> instead of <code>save</code> as depicted below:

<source lang="xml">
<window title="Save Resumable" border="normal">
	<button label="download"
	onClick='Filedownload.saveResumable("foo.txt", "text/plain", null)'/>
</window>

Then, the URL generated by saveResumable can be copied to the download manager the user prefers.

Control Resumable Download

Since the resumable download can be used in any session or without any session, or with a different client (such flashget), you might want to limit the download under certain condition. There are two library properties that can control the number of allowed resumable downloads.

• org.zkoss.zk.download.resumable.lifetime
  • Specifies when the download URL will be expired (unit: second).
  • Default: 14400 (i.e., 4 hours).
• org.zkoss.zk.download.resumable.maxsize
  • Specifies the maximal allowed number of resumable downloads.

(( Default: 4096.

If you want more advanced control, you can implement FiledownloadListener and specify it in a library property called org.zkoss.zkmax.zul.FiledownloadListener.class. For examle, in zk.xml, you can do:

<library-property>
  <name>org.zkoss.zkmax.zul.FiledownloadListener.class</name>
  <value>com.foo.MyDownloadListener</value>
</library-property>

Version History

Version	Date	Content