- 开发者指南 -

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\ 有读写权限

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\ 有读写权限

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.

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），看下例。
  

例程

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)
  参数：存储标识符...
  

例程

Blacklist:

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

初始化黑名单:

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

例程

Whitelist:

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

初始化白名单：

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

例程

Overwrite :

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

设置覆盖机能是否有效：

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

例程

File size limit:

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

限制上载文件大小

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

例程

Maximum uploaded files for a store :

UploadBean 可以限制上载文件数量。超过此限制UploadBean将抛出一个异常。


设置最大上载文件数量

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

例程

Store methods :

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


保存上载文件：

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

例程

MultipartFormDataRequest :

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

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

例程

Reset a store :

UploadBean 可以重设存储空间中的内容。对于数据库存储模式它将删除所有 记录。对于ZIP文件存储模式它将ZIP文件清空。对于文件夹存储模式它将删除 所有文件。对与内存存储模式它将清空内存。

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

• public void resetStore()
  无参数
  

例程

UploadListener :

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

注册监听器：

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

例程

History :

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

• public Vector getHistory()
  无参数
  

例程