JavaZOOM Web Site
  Software
  
Installation
  
Configuration
  
API & Design
  
License
<< back

- 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.

 

[News] [Applets] [Servlets] [Services] [Projects] [Links] [About]

Copyright © JavaZOOM 1999-2004

Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U. S. and other countries.
All other company and/or product names are the property of their respective owners.