UploadBean开发者指南

<选自官方http://www.javazoom.net/jzservlets/uploadbean/documentation_cn/developerguide.html#max>
UploadBean 是用于文件上载的组件(JAVA component)，你可以将上载的文件保存在服 务器的文件夹下或打包成ZIP文件保存在文件夹下，你还可以将文件保存在数据库中 或内存中。这份文档是面向开发者的，我们假设你已经了解一些组件JavaBeans和JSP 技术并且知道什么是组件作用"范围"(page, session, application)。
首先你需要选择存储模式：[Folder] [ZIP Archive] [Database] [Memory]。 此后你可以通 [setStoreModel] 方法进行切换。其次，你可以增加一些限定条件，比如：[blacklist] ， [whitelist]， [file size limit]， [maximum]上载文件大小。存储上载的文件你需要调用 [MultipartFormDataRequest] 对象的[store]方法。( [overwrite] 选项用于处理重复上载文件)。 最后，如果有必要你可以[reset]存储空间。当文件上载时实现[UploadListener]接口的类 可以接收到文件上载事件。上载文件的信息保存在[history] 中(非二进制文件)。UploadBean 支持两种解析器，你可以通过 [parser] 属性进行设置。

  Folder :

UploadBean 可以将文件上载到服务器的任意目录或文件夹下，Servlet引擎 必须有对该文件夹和目录的读写权限。

设置文件夹存储模式：

• public void setFolderstore(String serverfolder)
  参数:文件夹的完全路径 (e.g. /usr/uploads)。
  如果文件夹不存在系统将创建一个空文件夹。
  

Win32 OS.下的一个例程。我们假设Servlets引擎对D:/Inetpub/uploads/ 有读写权限

<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 可以将文件保存在ZIP文件中。Servlets引擎必须有对包含该ZIP文件的文件夹 的读写权限。

设置ZIP存储模式：

• public void setZipfilestore(String file)
  参数：ZIP文件的完全路径(e.g. /usr/upload/uploaded.zip).
  如果不存在系统将创建一个空ZIP文件。
  

Win32 OS.下的一个例程。我们假设Servlets引擎对D:/Inetpub/customers/ 有读写权限

<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 可以将上载文件保存在任意支持长原始（long RAW）数据(例如： 二进制文件）。你需要一个表(UPLOADS)，表中有三个字段：UPLOADID（主键） ，FILENAME（上载文件名），二进制数据(BINARYFILE)。你可以通过UploadBean类 的SQLUPLOAD* 公有静态成员变量更改表以及字段名字。

初始化JDBC连接 :

• public void setDatabasestore(String driver, String URL, Properties credentials)
  参数：JDBC driver标识，JDBC URL ，其它连接属性(用户名/口令)。
  此方法将驱动程序装载到内存里，并建立一个数据库连接。
• public void setDatabasestore(Connection jdbcconnection)
  参数：数据库连接名，该连接可以来自数据源（DataSource）或连接池。
  

替代数据库存储实现 :

• public void setDatabasestoreimplementation(String newimpl)
  参数：扩展于DBStore的类名称。看下面的注解5

下面是一个关于Oracle的例程。假设ORCL是一个运行在mydbhost服务器(port 1521) 上的数据库实例(login=test, password=test）。一个与upload_oracle.sqlscript中所描述结构相同的表。 我们也假设你使用的是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 and or 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 可以将上载的文件存储JVM内存中。已上载的文件将被存在一个"Vector"对象中。 这是一个"UploadFile"类型的Vector。 (更多信息看 API ).

设置内存存储模式：

• public void setStoremodel(int storeid)
  参数：内存存储标识符（MEMORYSTORE），看下例。
  

例程

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

切换存储模式。

• public void setStoremodel(int storeid)
  参数：存储标识符...
  

例程

<some HTML ...
  <jsp:setProperty name="upBean" property="storemodel"
   value="<%= UploadBean.ZIPFILESTORE %>" />
... some HTML>
Note :
- Each storemodel had to been initialized before swithing.

 Blacklist:

UploadBean 可以通过一个黑名单（blacklist）过滤上载的文件。黑名单中包含 你拒绝上载的文件名列表。如果上载列表中的文件，UploadBean将包抛出一个异常

初始化黑名单:

• public void setBlacklist(String list)
  参数：以逗号分割的文件名列表。
  

例程

<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 可以通过一个白名单（whitelist）过滤上载的文件。白名单中包含 可以上载的文件名列表。如果上载列表以外的文件UploadBean将抛出一个异常。 一个空的白名单将意味这你不能上载任何文件。黑名单和白名单不能同时使用 。默认是空的黑名单，这意味着所用文件被允许上载。

初始化白名单：

• public void setWhitelist(String list)
  参数：以逗号分割的文件名列表。
  

例程

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

 Overwrite :

UploadBean 可以检查出上载的文件是否重复，或覆盖或作为一个新的文件保存下来 （新文件名=原文件名+随机数）

设置覆盖机能是否有效：

• public void setOverwrite(boolean enable)
  参数：默认值为false，覆盖无效
  

例程

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

 File size limit:

UploadBean 可以限制上载文件的大小（单位：字节）。如果上载文件大小超 过限制的大小UploadBean将抛出一个异常

限制上载文件大小

• public void setFilesizelimit(int sizelimitinbytes)
  参数：文件大小限制（单位：字节）默认值：50MB.
  

例程

<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 可以限制上载文件数量。超过此限制UploadBean将抛出一个异常。


设置最大上载文件数量

• public void setMaxfiles(int amountallowed)
  参数：最大上载文件数。默认值：100
  

例程

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

 Store methods :

UploadBean 将上载的文件从MultipartFormDataRequest对象中抽出，存储到已指定 的存储空间中。存储之前UploadBean将检查所有的限定条件。


保存上载文件：

• public void store(MultipartFormDataRequest mrequest, String field)
  参数：MultipartFormDataRequest对象名，表单中file类型的控件名
• public void store(MultipartFormDataRequest mrequest)
  参数：MultipartFormDataRequest对象。UploadBean将保存对象中所有的有效文件。
  

例程

<%
  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 从MultipartFormDataRequest实例中抽取出上载的文件。这个类 从HTML表单中以"multipart/form-data"编码形式抽取数据。你需要设置你的 表单编码形式为"multipart/form-data" 。你不能用enctype="application/x-www-form-urlencoded"设置编码。

MultipartFormData不是UploadBean的核心,除了从表单中抽取参数和数值外，你不需要过 多的关心它。看API 学习更多的信息。

例程

<%
   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 可以重设存储空间中的内容。对于数据库存储模式它将删除所有 记录。对于ZIP文件存储模式它将ZIP文件清空。对于文件夹存储模式它将删除 所有文件。对与内存存储模式它将清空内存。

重新设置存储空间中的内容：

• public void resetStore()
  无参数
  

例程

<%
   upBean.resetStore();
%>

 UploadListener :

UploadBean 会通知监听器当上载的文件通过了限制条件检查并且已经保存。该监听器实 现UploadListener接口。传入的参数是一个UploadParameters类的实例，里面 包含了上载文件的信息（fileUploaded方法）

注册监听器：

• public void addUploadListener(UploadListener listener)
  参数：监听器实例
  

例程

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

 History :

UploadBean 跟踪所有已上载文件的信息(filename, filesize,content-type, storemodel, storeinfo)。你可以得到上载的历史纪录,一个UploadParameters类型的 Vector。
得到上载历史纪录：

• public Vector getHistory()
  无参数
  

例程

<%
    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 支持两种解析器（multipart parsers）：cos and struts。你可以通过 parser属性来选择一种。 默认为cos.

选择和设置解析器：

• public void setParser(String parserid)
  参数：解析器标识符
  MultipartFormDataRequest.COSPARSER 和
  MultipartFormDataRequest.STRUTSPARSER.
• public void setParsertmpdir(String tmpdir)
  Input 参数：允许选择的临时目录(cache) 仅对Struts解析器有效。
  

Struts 解析器例程

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