File Download

This documentation is for an older version of ZK. For the latest one, please click here.

The File Download Dialog

The org.zkoss.zul.Filedownload class provides a set of utilities to prompt a user for downloading a file from the server to the client. 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 download.html">
	<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>

The Resumable Download

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 wget and DownThemAll). 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 save method becomes obsolete as soon as the desktop (or session) is gone.

To use resumable download, you have to invoke the saveResumable method of the org.zkoss.zkmax.zul.Filedownload class (available in the Enterprise edition) instead of save as depicted below:

<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 {@link 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>