-
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] option
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 swithing.
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 random number
to filename extension.
One method is available to enable/disable overwriting :
- public
void setOverwrite(boolean enable)
Default is false, so overwrite is
disabled.
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 ans zip store, overwrite=false will append System.currentTimeMillis()
to duplicate filename.
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 Struts 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.STRUTSPARSER
%>"/>
<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.
|