- Configuration -
Download4J is a JAVA component (Servlet + JavaBean) that allows to download files from a source as folder,a ZIP archive or database (Oracle, DB2, MySQL ...). To setup Download4J you need to write or customize an XML configuration file. There is one configuration file per source : [Folder], [ZIP archive] and [Database]. You could define global and file-specific download attributes such as counters, login/password, URL mapping, zip-on-the-fly ... Finally, you have to declare this configuration file and download URL mapping into Download4J deployment descriptor then end-users could download files through a given URL. Downloads traces such as date & time, end-user IP address and hits are available too.
Download Source : Folder |
Download4J can download files stored in any folder or directory. The folder and files must have read access.
Here is a sample of Download4J configuration file :
XML
Sample for FOLDER source : folder.xml |
<DOWNLOAD>
<FOLDER
ID="uniqueid"
PATH="">
<PROPERTIES CONTENT-TYPE-FILE="conf/mimes-type.xml"/>
<FILE
NAME="protectedtest.pdf"
MAXDOWNLOAD="3" LOGIN="login"
PASSWORD="password"/>
<FILE
NAME="ziptest.html"
URLMAPPING="ziptest.zip" ZIP="enabled"/>
</FOLDER>
</DOWNLOAD> |
|
To get more information about each XML tag and attribute see below :
XML
TAG : FOLDER |
Info |
PATH
: |
Folder
path where Download4J will find files to download.
(e.g. /usr/download or D:/Downloads). This attribute
is mandatory. PATH="" means that default
folder is $YOUR_WEB_APP_HOME/WEB-INF/downloadroot |
ID
: |
Unique
id that identifies the folder (needed if multiple
folders). This attribute is mandatory. |
DESC
: |
Optional
description of the folder. |
|
XML
TAG : PROPERTIES |
Info |
PATH
: |
Folder
path where Download4J could find content type file
below (e.g. /usr/conf). Default is $YOUR_WEB_APP_HOME/WEB-INF |
CONTENT-TYPE-FILE
: |
Filename
(and optionally relative path) of XML mime types.
(e.g. mimes-type.xml). This attribute is mandatory.
This file maps file extension (.txt, .zip, .doc
...) to its content type (plain/text, application/zip,
application/msword ...). |
CONTENT-DISPOSITION
: |
Regardless
to content-type, ask the browser to display the
file or to save it after the download. "inline"
value means display in browser or matching application,
"attachment" value means save on disk
prompt. |
LOGIN
: |
Login
to protect alls downloads (e.g. test). |
PASSWORD
: |
Password
to protect the alls download (e.g. test). |
ZIP
: |
Enables/disables
zip on-the-fly for all downloads. Values could be
: "enabled" or "disabled" only. |
|
XML
TAG : FILE |
Info |
PATH
: |
Folder
path for the file to download. This path overrides
path's value in properties xml tag (e.g. /usr/anotherfolder). |
NAME
: |
Filename
to download from folder (e.g. filetest.txt). This
attribute is mandatory. |
URLMAPPING
: |
URL
mapping for the file to download (e.g. file.txt).
This mapping is should be considered as an alias. |
CONTENT-TYPE
: |
Content
type for the file to download (e.g. application/msword).
Default content types are loaded from content type
file defined in properties xml tag. |
CONTENT-DISPOSITION
: |
Regardless
to content-type, ask the browser to display the
file or to save it after the download. "inline"
value means display in browser or matching application,
"attachment" value means save on disk
prompt. |
MAXDOWNLOAD
: |
Maximum
download hits for the file (e.g. 3). When limit
is reached, end-user get an HTTP 403 error : "Downloads
limit reached". |
LOGIN
: |
Login
to protect the download (e.g. logintest). This login
overrides the properties' login value. |
PASSWORD
: |
Password
to protect the download (e.g. passwordtest). This
password overrides the properties' password value. |
ZIP
: |
Enables/disables
zip on-the-fly on download. This value overrides
the properties' value. Values could be : "enabled"
or "disabled" only. |
CUSTOM
: |
Custom
parameter that could be passed to DownloadSource
implementation. This parameter could be overwritten
through the URL :
http://yourserver.com/d4j/download?name=test.pdf&custom=1578 |
|
Notes :
1 - Don't pay attention about "/" or "\" in path. Download4J will use always use the good one.
2 - DO NOT add "/" or "\" at the end of path.
3 - LOGIN="" and PASSWORD="" in FILE tag means the file is not protected.
4 - A full sample is available through foldersample.jsp
Download Source : ZIP Archive |
Download4J can download files stored in a ZIP archive. This archive must have read access.
Here is a sample of Download4J configuration file :
XML
Sample for ZIP source : zip.xml |
<DOWNLOAD
LOGLEVEL="2" LOGFOLDER="E:/Download4J">
<ZIP
ID="uniqueid"
PATH="E:/Download4J/downloadroot/test.zip">
<PROPERTIES CONTENT-TYPE-FILE="conf/mimes-type.xml"/>
<FILE
NAME="protectedtest.pdf"
MAXDOWNLOAD="3" LOGIN="login"
PASSWORD="password"/>
<FILE
NAME="ziptest.html"
URLMAPPING="ziptest.zip" ZIP="enabled"/>
</ZIP>
</DOWNLOAD> |
|
To get more information about each XML tag and attribute see below :
XML
TAG : ZIP |
Info |
PATH
: |
ZIP
archive filename (with full path) where Download4J
will find files to download. (e.g. /usr/archive.zip
or D:/archive.zip). This attribute is mandatory.
PATH="" means that default ZIP archive
is $YOUR_WEB_APP_HOME/WEB-INF/downloadroot.zip |
ID
: |
Unique
id that identifies the ZIP (needed if multiple ZIP
archives). This attribute is mandatory. |
DESC
: |
Optional
description of the archive. |
|
XML
TAG : PROPERTIES |
Info |
PATH
: |
Folder
path where Download4J could find content type file
below (e.g. /usr/conf). Default is $YOUR_WEB_APP_HOME/WEB-INF |
CONTENT-TYPE-FILE
: |
Filename
(and optionally relative path) of XML mime types.
(e.g. mimes-type.xml). This attribute is mandatory.
This file maps file extension (.txt, .zip, .doc
...) to its content type (plain/text, application/zip,
application/msword ...). |
CONTENT-DISPOSITION
: |
Regardless
to content-type, ask the browser to display the
file or to save it after the download. "inline"
value means display in browser or matching application,
"attachment" value means save on disk
prompt. |
LOGIN
: |
Login
to protect alls downloads (e.g. test). |
PASSWORD
: |
Password
to protect the alls download (e.g. test). |
ZIP
: |
Enables/disables
zip on-the-fly for all downloads. Values could be
: "enabled" or "disabled" only. |
|
XML
TAG : FILE |
Info |
PATH
: |
ZIP
archive filename (with full path) for the file to
download. This path overrides path's value in properties
xml tag (e.g. /usr/anotherarchive.zip). |
NAME
: |
Filename
to download from ZIP archive (e.g. filetest.txt).
This attribute is mandatory. |
URLMAPPING
: |
URL
mapping for the file to download (e.g. file.txt).
This mapping is should be considered as an alias. |
CONTENT-TYPE
: |
Content
type for the file to download (e.g. application/msword).
Default content types are loaded from content type
file defined in properties xml tag. |
CONTENT-DISPOSITION
: |
Regardless
to content-type, ask the browser to display the
file or to save it after the download. "inline"
value means display in browser or matching application,
"attachment" value means save on disk
prompt. |
MAXDOWNLOAD
: |
Maximum
download hits for the file (e.g. 3). When limit
is reached, end-user get an HTTP 403 error : "Downloads
limit reached". |
LOGIN
: |
Login
to protect the download (e.g. logintest). This login
overrides the properties' login value. |
PASSWORD
: |
Password
to protect the download (e.g. passwordtest). This
password overrides the properties' password value. |
ZIP
: |
Enables/disables
zip on-the-fly on download. This value overrides
the properties' value. Values could be : "enabled"
or "disabled" only. |
CUSTOM
: |
Custom
parameter that could be passed to DownloadSource
implementation. This parameter could be overwritten
through the URL :
http://yourserver.com/d4j/download?name=test.pdf&custom=1578 |
|
Notes :
1 - Don't pay attention about "/" or "\" in path. Download4J will use always use the good one.
2 - DO NOT add "/" or "\" at the end of path.
3 - LOGIN="" and PASSWORD="" in FILE tag means the file is not protected.
4 - A full sample is available through zipsample.jsp
Download Source : Database |
Download4J can download files stored in database (Oracle, IBM DB2, MySQL, ...). Database instance, schema and data must be available.
We provide sample SQL scripts to create and populate a DOWNLOAD table with files you could find under WEB-INF/downloadroot (download_oracle.sql, download_db2.sql, download_mysql.sql). Note that you have to check, the JDBC driver matching to your database, is in your web application CLASSPATH. Download4J doesn't include these JDBC drivers.
Here is a sample of Download4J configuration file :
XML
Samples for DATABASE source : database_oracle.xml,
database_mysql.xml,
database_db2.xml |
<DOWNLOAD
LOGFOLDER="">
<DATABASE
ID="uniqueid"
DRIVER="oracle.jdbc.driver.OracleDriver"
URL="jdbc:oracle:thin:@MYSERVER:1521:ORCL"
DBLOGIN="scott"
DBPASSWORD="tiger">
<SCHEMA
TABLE="DOWNLOAD"
DATACOLUMN="BINARYFILE"
FILENAMECOLUMN="FILENAME"/>
<PROPERTIES
CONTENT-TYPE-FILE="conf/mimes-type.xml"/>
<FILE
NAME="protectedtest.pdf" MAXDOWNLOAD="3"
LOGIN="login" PASSWORD="password"/>
<FILE
NAME="ziptest.html" URLMAPPING="ziptest.zip"
ZIP="enabled"/>
</DATABASE>
</DOWNLOAD> |
|
To get more information about each XML tag and attribute see below :
XML
TAG : DATABASE |
Info |
DRIVER
: |
JDBC
driver classname. Download4J will load it in memory
(e.g. oracle.jdbc.driver.OracleDriver). This attribute
is mandatory. |
URL
: |
JDBC
URL to connect to the database (e.g. jdbc:oracle:thin@myrdbms:1521:ORCL). |
DBLOGIN
: |
Database
account login (e.g. scott) |
DBPASSWORD
: |
Database
account password (e.g. tiger) |
IMPL
: |
DownloadSource
classname for custom implementation (e.g. com.yourcompany.CustomDownloadSource).
Download4J allows developers to
replace default database "extractor" with
another one that suits to their needs (schema, SQL
requests, ...). The custom implementation must extends
javazoom.download.DownloadSource class. See API
to learn more. |
ID
: |
Unique
id that identifies the database (needed if multiple
database). This attribute is mandatory. |
DESC
: |
Optional
description of the database. |
|
XML
TAG : SCHEMA |
Info |
TABLE
: |
Table
name where Download4J could find files to download
(e.g. downloads). This attribute is mandatory. |
DATACOLUMN
: |
Column
name where Download4J could find (binary) data matching
to the file to download (e.g. binaryfile). This
attribute is mandatory. |
FILENAMECOLUMN
: |
Column
name where Download4J could find filenames matching
to the file to download (e.g. filename). This attribute
is mandatory. |
|
XML
TAG : PROPERTIES |
Info |
PATH
: |
Folder
path where Download4J could find content type file
below (e.g. /usr/conf). Default is $YOUR_WEB_APP_HOME/WEB-INF |
CONTENT-TYPE-FILE
: |
Filename
(and optionally relative path) of XML mime types.
(e.g. mimes-type.xml). This attribute is mandatory.
This file maps file extension (.txt, .zip, .doc
...) to its content type (plain/text, application/zip,
application/msword ...). |
CONTENT-DISPOSITION
: |
Regardless
to content-type, ask the browser to display the
file or to save it after the download. "inline"
value means display in browser or matching application,
"attachment" value means save on disk
prompt. |
LOGIN
: |
Login
to protect alls downloads (e.g. test). |
PASSWORD
: |
Password
to protect the alls download (e.g. test). |
ZIP
: |
Enables/disables
zip on-the-fly for all downloads. Values could be
: "enabled" or "disabled" only. |
|
XML
TAG : FILE |
Info |
PATH
: |
Not
Applicable. This attribute should not be used. |
NAME
: |
Filename
to download from FILENAMECOLUMN (e.g. filetest.txt).
This attribute is mandatory. |
URLMAPPING
: |
URL
mapping for the file to download (e.g. file.txt).
This mapping is should be considered as an alias. |
CONTENT-TYPE
: |
Content
type for the file to download (e.g. application/msword).
Default content types are loaded from content type
file defined in properties xml tag. |
CONTENT-DISPOSITION
: |
Regardless
to content-type, ask the browser to display the
file or to save it after the download. "inline"
value means display in browser or matching application,
"attachment" value means save on disk
prompt. |
MAXDOWNLOAD
: |
Maximum
download hits for the file (e.g. 3). When limit
is reached, end-user get an HTTP 405 error : "Downloads
limit reached". |
LOGIN
: |
Login
to protect the download (e.g. logintest). This login
overrides the properties' login value. |
PASSWORD
: |
Password
to protect the download (e.g. passwordtest). This
password overrides the properties' password value. |
ZIP
: |
Enables/disables
zip on-the-fly on download. This value overrides
the properties' value. Values could be : "enabled"
or "disabled" only. |
CUSTOM
: |
Custom
parameter that could be passed to DownloadSource
implementation. This parameter could be overwritten
through the URL :
http://yourserver.com/d4j/download?name=test.pdf&custom=1578 |
|
Notes :
1 - Don't pay attention about "/" or "\" in path. Download4J will use always use the good one.
2 - DO NOT add "/" or "\" at the end of path.
3 - LOGIN="" and PASSWORD="" in FILE tag means the file is not protected.
4 - A full sample is available through databasesample.jsp
Select Source and URL Mapping for downloads : |
Once you've setup the XML configuration file matching to your downloads source (Folder, ZIP or Database) you have to declare path this file into
WEB-INF/web.xml. You might also want to modify download URL mapping.
Here is below the web.xml file included in Download4J :
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
<servlet>
<servlet-name>downloadservlet</servlet-name>
<servlet-class>javazoom.download.DownloadServlet</servlet-class>
<init-param>
<param-name>configfile</param-name>
<param-value>conf/folder.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>downloadservlet</servlet-name>
<url-pattern>/download/*</url-pattern>
</servlet-mapping>
</web-app> |
|
- Select configuration file :
As you could see in <param-value> tag above, default path to configuration file is conf/folder.xml (i.e. full path is $YOUR_WEBAPP_HOME/WEB-INF/conf/folder.xml). If you need to setup a database source you have modify it to conf/database.xml and conf/zip.xml for ZIP source.
- Setup download URL mapping :
As you could see in <url-pattern> tag, download URL mapping is /download/*
What does it mean ? If end-user want to download testfile.exe then he will use :
http://server.com/download4j/download/testfile.exe
For instance, you could modify it to /files/* then end-user URL will become :
http://server.com/download4j/files/testfile.exe
- Setup bean ID :
To get information about downloads (downloadlink, maxdownload, totaldownload ...) you will need a downloadbean instance in your JSP.
<jsp:useBean id="downloadbean" class="javazoom.download.DownloadBean" scope="page" />
[...]
<%
Repository repository = Repository.getInstance();
Config conf = repository.get("uniqueid");
downloadbean.setConfig(conf);
downloadbean.setVirtualPath(request.getContextPath()+"/download");
%>
[...]
<%= downloadbean.getDownloadLink("globaltest.txt") %>
<%= downloadbean.getTotalDownload("globaltest.txt") %>
[...]
Note : If you don't want to the configuration file to be under $YOUR_WEBAPP_HOME/WEB-INF/conf then add a new configpath init-param with the absolute path. For instance : |
[...]
<init-param>
<param-name>configpath</param-name>
<param-value>d:/anotherfolder</param-value>
</init-param>
<init-param>
<param-name>configfile</param-name>
<param-value>zip.xml</param-value>
</init-param>
[...] |
|
Download URLs : |
- Download URL :
Depending on download URL mapping (default is /download/*), download urls for a file "testfile.exe" could be either :
http://server.com/download4j/download/testfile.exe
Or :
http://server.com/download4j/download?name=testfile.exe
- Download URL for multiple folders, zip archives or databases :
Depending on download URL mapping (default is /download/*), download url for a file "testfile.exe" from folder identified my "uniqueid" must be :
http://server.com/download4j/download/testfile.exe?id=uniqueid
Or :
http://server.com/download4j/download?name=testfile.exe&id=uniqueid
Notes :
1 - Use <%= downloadbean.getDownloadLink("testfile.exe") %> to generate URL .
Traces : |
Each XML configuration file starts with a <DOWNLOAD> tag. You could add attributes to setup traces level and folder. Traces are dumped into files, created in LOGFOLDER, on servlet engine startup.
Traces filenames look like : download4j-yyyy-MM-dd_HH-mm.log and traces format is : [yyyy/MM/dd HH:mm] full.qualified.classname : message
Three levels are available for traces (LOGLEVEL) :
0 = Panic messages (download can't be processed)
1 = Panic + Info messages such download hits, date & time, end-user IP, Authentication.
2 = Panic + Info + Debug messages.
Default level is 0.
Here is sample DOWNLOAD tag :
XML
Sample : |
<DOWNLOAD
LOGLEVEL="2" LOGFOLDER="E:/Download4J">
...
</DOWNLOAD> |
|
LOGFOLDER="" means that traces will be dumped under $YOUR_WEBAPP_HOME/WEB-ING
No LOGFOLDER attribute means that traces wil be displayed on standard ERR output.
|