JavaZOOM Web Site UploadBean homepage
  Software
  
Installation
  
Developer Guide
  API & Design
  
License

<< back

- Developer Guide -

UploadBean is a JavaBean (JAVA component) that allows to upload files in store. This store could be a folder, a ZIP archive, a database or memory. This document is a guide for developers. We assume that developers have a few JavaBeans and JSP skills and they know what "scope" (page, session, application) is for JavaBeans.
First of all, you need to select a store model : [Folder] [ZIP Archive] [Database] [Memory]. Once selected, you could switch to another model through [setStoreModel] method. Second, you can add some restrictions on uploaded files like a [blacklist] or
a [whitelist], a [file size limit] and a [maximum] store size. To store uploaded files, you have to call [store] method with a [MultipartFormDataRequest] object (see [overwrite] options for duplicate entries). Finally, you can [reset] store if needed. Any object implementing [UploadListener] interface could be notified when an uploaded file is stored. Note that an [history] of uploaded parameters (files without binary data) is available. Finally, UploadBean supports three multipart parsers. You could select one through [parser] property.

  Folder :

UploadBean can store uploaded files in any folder or directory. The folder must have read/write access. Uploaded files will be added under this folder.

One method is available to initialize the folder store :

  • public void setFolderstore(String serverfolder)
    Input parameter is the full path to the folder (e.g. /usr/uploads).
    This method will create an empty folder if needed.

Here is a sample under a Win32 OS. We assume that D:\Inetpub\uploads\ folder is RW for the process running the Servlets/JSP Engine.

<jsp:useBean id="upBean" scope="page" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="folderstore"
   value="D:/Inetpub/uploads" />
</jsp:useBean>

Notes :
1 - Don't pay attention about "/" or "\" in path. UploadBean will use always use the good one.
2 - DO NOT add "/" or "\" at the end
3 -
A full sample is available through SimpleUpload.jsp

 ZIP Archive :

UploadBean can store uploaded files in a ZIP archive. The folder containing the ZIP file must have read/write access. Uploaded files will be appended to the archive by creating a temporary archive.

One method is available to initialize the ZIP store :

  • public void setZipfilestore(String file)
    Input parameter is the full path to the ZIP file (e.g. /usr/upload/uploaded.zip).
    This method will create an empty ZIP archive if needed.

Here is a sample under a Win32 OS. We assume that D:\Inetpub\customers\ is RW for the process running the Servlets/JSP Engine.

<jsp:useBean id="upBean" scope="session" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="zipfilestore"
   value="D:/Inetpub/customers/uploads.zip" />
</jsp:useBean>

Notes :
1 - Appending process could be slow because UploadBean need to create a temporary archive. Try to avoid big archives.
2 - Don't pay attention about "/" or "\" in path. UploadBean will use always use the good one.
3 -
A full sample is available through MultipleUploads.jsp

 Database :

UploadBean can store uploaded files in any database supporting long RAW data (i.e. binary files). You need a table (UPLOADS) with one column for upload identifiers (UPLOADID), one column for uploaded filenames (FILENAME) and one column for binary data (BINARYFILE). Note that you can modify tables and columns names through SQLUPLOAD* public static fields of UploadBean class.

Two methods are available to initialize to JDBC connection :

  • public void setDatabasestore(String driver, String URL, Properties credentials)
    Inputs parameters are the JDBC driver identifier, the JDBC URL and some connection properties (usually login/password).
    This method will load the driver in memory and open a database connection.
  • public void setDatabasestore(Connection jdbcconnection)
    Input parameter is a database connection that could come from a DataSource or any connection pool.

One method is available to replace database store implementation :

  • public void setDatabasestoreimplementation(String newimpl)
    Inputs parameter is your extended DBStore classname. See note 5 below.

Here is a sample for Oracle. We assume that ORCL is a database instance running on mydbhost server (port 1521) and a test (login=test, password=test) account is available. A table matches to the upload_oracle.sql script. We also assume that we're using the Oracle THIN JDBC driver.

<jsp:useBean id="upBean" scope="application" class="javazoom.upload.UploadBean">
<%
  Properties props = new Properties();
  props.put("user","test");
  props.put("password","test");
  upBean.setDatabasestore("oracle.jdbc.driver.OracleDriver",
  
 "jdbc:oracle:thin:@mydbhost:1521:ORCL", props);
%>
</jsp:useBean>

Notes :
1 - "scope=application" is recommended to avoid multiples database connections."scope=session is acceptable small amount of users. "scope=request" is not recommended without JDBC ConnectionPool.
2 - UploadBean won't close the database connection. You can do it when needed by calling :
upBean.getDatabasestore().close(
)
3 -
A full sample is available through DatabaseUpload.jsp

4 - For DB2 script see upload_db2.sql, for PostGreSQL see upload_postgresql.sql and for MySQL script see upload_mysql.sql
5 - If UploadBean database store does not suit to your needs then you could implement your own DBStore. A sample is available in add-ons section.

 Memory :

UploadBean can store uploaded files in JVM memory. Uploaded files will be stored in a "Vector" object. This is a vector of "UploadFile" objects (see API to learn more).

One method is available to initialize the memory store :

  • public void setStoremodel(int storeid)
    Input parameter is a store identifier for MEMORYSTORE.

Here is a sample.

<jsp:useBean id="upBean" scope="session" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="storemodel"
   value="<%= UploadBean.MEMORYSTORE %>" />

</jsp:useBean>

Notes :
1 - Using memory store without "scope=session" or
"scope=application" is not really useful.
2 - You can access the memory store through upBean.getMemorystore().
3 - All data will be lost when the servlet engine stops (or crashes).

 Switch to another model :

One method is available to switch to another store model. It could be useful if, depending on file's Content-Type, you want to switch to folder or zipfile store.

  • public void setStoremodel(int storeid)
    Input parameter is a store identifier..

Here is a sample.

<some HTML ...
  <jsp:setProperty name="upBean" property="storemodel"
   value="<%= UploadBean.ZIPFILESTORE %>" />
... some HTML>

Note
:
- Each storemodel had to been initialized before switching.


 Blacklist:

UploadBean can filter uploaded files through a blacklist. A blacklist is a list of filenames you don't want to be uploaded/stored (i.e list of denied filenames). If someone try to upload a forbidden file then UploadBean will throw an exception.

One method is available to initialize the blacklist :

  • public void setBlacklist(String list)
    Input parameter is a list of filenames seperated by coma.

Here is a sample.

<jsp:useBean id="upBean" scope="session" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="blacklist"
   value="*.zip,*.rar,setup.exe" />

</jsp:useBean>


 Whitelist:

UploadBean can filter uploaded files through a whitelist. A whitelist is a list of filenames that could be uploaded/stored (i.e list of allowed filenames). If someone try to upload a file NOT in whitelist then UploadBean will throw an exception. An empty whitelist means that you can't upload any file. UploadBean allows Blacklist or Whitelist but NOT both. Default is an empty blacklist (all files allowed).

One method is available to initialize the blacklist :

  • public void setWhitelist(String list)
    Input parameter is a list of filenames seperated by coma.

Here is a sample.

<jsp:useBean id="upBean" scope="session" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="whitelist" value="*.ogg,*.mp3" />

</jsp:useBean>


 Overwrite :

UploadBean can check for duplicates entries on upload. Then it can overwrite the entry or create a new entry by appending a timestamp to filename extension.

One method is available to enable/disable overwriting and one for renaming option :

  • public void setOverwrite(boolean enable)
    Default is false, so overwrite is disabled.
  • public void setOverwritepolicy(String policy)
    When overwrite is false, UploadBean could append unix-like timestamp after the file extension (e.g. filename.zip.123456789) with policy="filenametimestamp" or after the file name (e.g. filename_123456789.zip) with policy="nametimestamp". For others policy values it will insert the given parameter, for instance if overwrite policy="_test123" then renamed file with be filename_test123.zip.

Here is a sample.

<jsp:useBean id="upBean" scope="session" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="overwrite"
   value="true" />
</jsp:useBean>

Notes :
1 - For folder and zip store, you could get the new filename through UploadParameters.getAltFilename().     
2 - For database store (default implementation), overwrite=false will insert a new record,
     overwrite=true will update it.

3 - For memory store, all uploaded files are appended to a list. overwrite is useless

 File size limit:

UploadBean can filter uploaded files on size. The file size limit is in bytes. If someone try to upload a file which size is above of the one allowed then UploadBean will throw an exception.

One method is available to setup file size limit :

  • public void setFilesizelimit(int sizelimitinbytes)
    Input parameter is file size limit in bytes. Default is 1GB.

Here is a sample.

<jsp:useBean id="upBean" scope="session" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="filesizelimit"
   value="1048576" />
</jsp:useBean>


 Maximum uploaded files for a store :

UploadBean can manage stores with upper limit. The limit is the maximum number of uploaded files. If someone try to upload more files than allowed by the current store then UploadBean will throw an exception.

One method is available to setup maximum files for the current store :

  • public void setMaxfiles(int amountallowed)
    Input parameter is the maximum number of files in a store. Default is -1 (unlimited).

Here is a sample.

<jsp:useBean id="upBean" scope="session" class="javazoom.upload.UploadBean">
  <jsp:setProperty name="upBean" property="maxfiles"
   value="10" />
</jsp:useBean>


 Store methods :

UploadBean moves uploaded file(s) from MultipartFormDataRequest object to the defined store. UploadBean will check all restrictions before storing file(s).


Two methods are available to store uploaded files from MultipartFormDataRequest :

  • public void store(MultipartFormDataRequest mrequest, String field)
    Inputs parameters are a MultipartFormDataRequest object and the form field identifier matching to the file you want to store.
  • public void store(MultipartFormDataRequest mrequest)
    Input parameter is a MultipartFormDataRequest object. UploadBean will save all files available in the MultipartFormDataRequest object.

Here is a sample.

<%
  if (MultipartFormDataRequest.isMultipartFormData(request))
  {
      // Uses MultipartFormDataRequest to parse the HTTP request.
      MultipartFormDataRequest mrequest = new MultipartFormDataRequest(request);
      upBean.store(mrequest);
  }
%>

Notes :
1 - UploadBean will not save anything if you don't call this method.
2 - In the example above, request is the implicit HttpServletRequest object.
3 - Store is synchronized for ZIP Archive so don't worry about file locking.


 MultipartFormDataRequest :

UploadBean extracts uploaded file(s) from a MultipartFormDataRequest instance. This class handles "multipart/form-data" enctype from your HTML form. You need to encode form data as "multipart/form-data" to upload files through a browser. You can't use enctype="application/x-www-form-urlencoded".

MultipartFormData is not the core of UploadBean, you don't need it except to get form parameters and values. See API to learn more about it.

Here is a sample.

<%
   if (MultipartFormDataRequest.isMultipartFormData(request))
   {
       // Uses MultipartFormDataRequest to parse the HTTP request.
       MultipartFormDataRequest mrequest = new MultipartFormDataRequest(request);
       String todo = mrequest.getParameter("todo");
       if ( (todo != null) && (todo.equalsIgnoreCase("upload")) )
       {
          ...
%>

Notes :
1 - In the example above, request is the implicit HttpServletRequest object.
2 - In addition to parser property you could select the multipart parser through the MultipartFormDataRequest constructor.


 Reset a store :

UploadBean can reset store. For database store it will delete records. For ZIP Archive store it will empty archive. For folder store it will delete all files. For memory store it will free memory.

One method is available to reset store :

  • public void resetStore()
    No input parameters.

Here is a sample.

<%
   upBean.resetStore();
%>


 UploadListener :

UploadBean can notify listeners implementing UploadListener interface. Notification will be done only if restrictions are passed and uploaded file is stored. Callback parameter is an UploadParameters instance (file info).

One method is available to register a listener :

  • public void addUploadListener(UploadListener listener)
    Input parameter is the listener instance.

Here is a sample.

some Java code
   ...
   myListener lst=new myListener();
   upBean.addUploadListener(lst);
   ...


 History :

UploadBean tracks all uploaded files information (filename, filesize, content-type, storemodel, storeinfo). You can get the history of uploads (Vector of UploadParameters).

One method is available to get history :

  • public Vector getHistory()
    No input parameters.

Here is a sample.

<%
    Vector history = upBean.getHistory();
    for (int i=0;i<history.size();i++)
    {
        UploadParameters up = (UploadParameters) history.elementAt(i);
        out.println("<li>Uploaded file : "+up.getFilename()+" ("+up.getFilesize()+
        "bytes)"+"<BR> Content Type : "+up.getContenttype());
        out.println("<BR>StoreModel : "+up.getStoremodelname()+
        " ("+up.getStoreinfo()+")");
    }
%>

 Parser :

UploadBean supports two multipart parsers (cos and struts). You can select one through parser property. Default one is cos.

Two methods are available to select and setup parser :

  • public void setParser(String parserid)
    Input parameter is a string that could take values among MultipartFormDataRequest.COSPARSER,
    MultipartFormDataRequest.STRUTSPARSER and
    MultipartFormDataRequest.CFUPARSER.
  • public void setParsertmpdir(String tmpdir)
    Input parameter allowing to select the tempory directory (cache) for Struts and Commons-FileUpload parsers only.

Here is a sample for CFU parser.

<jsp:useBean id="upBean" scope="page" class="javazoom.upload.UploadBean" >
  <jsp:setProperty name="upBean" property="folderstore" value="D:/uploads"/>
  <jsp:setProperty name="upBean" property="parser"
    value="<%= MultipartFormDataRequest.CFUPARSER %>"/>
  <jsp:setProperty name="upBean" property="parsertmpdir" value="D:/temp"/>
</jsp:useBean>

Notes :
1 -
To learn more about pros and cons of multipart parser check you the following thread in our online forum.


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

Copyright © JavaZOOM 1999-2006

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.