云存储FSS使用规范

1 FSS适用场景

1.1  FSS Server是基于云计算平台的文件存储系统，提供基于HTTP的文件上传、下载功能。

1.2  FSS适用于较小文件的存储，上传文件大小超过300M，需要向架构组邮件申请，标注文件的来源、用途、生命周期。 

1.4  FSS提供了客户端包，应用程序只需使用FSS Client提供的ＡＰＩ就可接入到FSS Server。

1.3  生产环境FSS Server只向内部应用暴露网络权限，诸如在website网页的img src中直接引用fss文件url的处理是不行的。 

 

2 FSS客户端使用规范

客户端版本

if-fss-client-4.3.45.1.jar是目前最新版本。4.3.44.5之前是旧版本。

新版本的变化：

• 新增了一些指定生命周期的上传方法，旧的上传方法不再建议使用。
• 增加了使用io流或byte[]数组作为上传下载来源或目的地的方法，可以不用先自已存到硬盘再上传，或先下载到硬盘再自读内容。
• 增加了删除文件的方法
• 提供了带网络超时参数的上传下载方法，可以不用默认的超时时间

新接入的应用应该使用最新的接入jar包。

已使用旧jar包的可以直接替换新版jar包升级，不用修改代码，jar包向前兼容。但建议升级jar包同时把代码中的旧方法调用改为新方法调用。

 

API使用规范

1 标注为@Deprecated的方法不再建议使用，请参考文档使用替代方法

2 上传文件都需要指定该文件的生命周期，如果文件需要长期保留，可以指定生命周期为永久保存。生命周期可以有效控制文件系统的文件增长速度。

3 建议在文件使用完毕后调用delete方法主动删除文件，以腾出空间。

4 对于大文件的上传下载，除了按1.2的要求报备外，需要适当的调整网络超时参数

5 api中一部分方法接收io资源为参数，请自行进行io资源的关闭等处理

6 直接将byte数组存为文件和将文件直接加载到byte数组的方法（getFileContent,putFileContent），只适用于极小的文件，一般情况请使用以io流为参数的方法

 

3 FSS文件治理

1 appCode命名

   上传文件时需要appCode参数，此参数由各组自行命名，但建议为不同类型的文件命名单独的appCode，以便在分配资源，文件清理等方面能得到有区别的对待。（可联系架构组对某appCode下文件需要的资源和清理策略作出说明）

2 文件清理

   1）对于未提供生命周期参数（如旧版接口）上传的文件，将保留清理的权利。

   2）FSS系统记录了文件下载的情况，长时间未被下载的文件将被优先清理，目前暂定，未指定生命周期的文件，一年未被下载将被清理。

   2）各组对遗留文件清理有不同要求的，可联系架构组专门说明。

================================================================================================================

1 简介

 

FSS Server是基于云计算平台的文件存储系统。FSS Server提供基于HTTP的文件上传、下载功能，应用程序只需使用FSS Client提供的ＡＰＩ就可接入到FSS Server。附件是接入手册，请下载查看。

2 接入步骤

2.1 依赖配置

依赖程序的IVY参考配置如下（如使用MAVEN，请作相应转换）：

<dependency org="org.apache" name="commons-net" rev="3.0.1" conf="zip->default" />
<dependency org="org.apache" name="commons-fileupload" rev="1.2.1" conf="zip->default" />
<dependency org="org.apache" name="commons-io" rev="1.4" conf="zip->default" />
<dependency org="org.apache" name="commons-lang" rev="2.4" conf="zip->default" />
<dependency org="org.apache" name="commons-collections" rev="3.2.1" conf="zip->default" />
<dependency org="org.apache" name="commons-beanutils" rev="1.8.3" conf="zip->default" />
<dependency org="org.apache" name="httpclient" rev="4.1" conf="zip->default" />
<dependency org="org.apache" name="httpclient-cache" rev="4.1" conf="zip->default" />
<dependency org="org.apache" name="httpcore" rev="4.1" conf="zip->default" />
<dependency org="org.apache" name="httpmime" rev="4.1" conf="zip->default" />
<dependency org="org.spring" name="spring" rev="2.5.5" conf="zip->default" />
<dependency org="com.99bill" name="if-fss-client" rev="4.3.45.1" conf="zip->default" />

注意：针对上述红色部分，请获取最新版本号。

 如果不使用Spring框架，则不需要org.spring。

2.2 nfs中的Properties文件

确保/nfs/envconfig/pmd/if/ if-fss-client.properties文件存在，开发测试、Stage2、Online环境的内容如下，仅供参考。
开发测试环境的内容为：

# development
fss.client.serverSites=http://192.168.51.100:8083/if-fss-server
# common
fss.client.getURL=/FileDownload
fss.client.uploadURL=/FileUpload
fss.client.listURL=/FileList

Stage2环境的内容为：

# stage2
#fss.client.serverSites=http://192.168.8.165/fss-server
# common
fss.client.getURL=/FileDownload
fss.client.uploadURL=/FileUpload
fss.client.listURL=/FileList

生产环境的内容为：

fss.client.serverSites= http://tomcat-3.99bill.com:8085/fss-server, http://tomcat-4.99bill.com:8085/fss-server
# common
fss.client.getURL=/FileDownload
fss.client.uploadURL=/FileUpload
fss.client.listURL=/FileList

 

2.3 开通防火墙

在生产环境部署时，请联系IDC申请开通访问FSS Server 机器tomcat-3.99bill.com/ tomcat-4.99bill.com的8085端口。开发、测试、Stage2环境不需此操作。

2.4 接入程序

2.4.1 Spring 方式

如果应用程序使用到Spring框架，则在应用程序的相关Spring配置中增加如下片段：

<import resource="classpath:context/fssPropertyLoader.xml"/>
<bean id="fssClient" class="com.bill99.golden.inf.fss.client.FSSClient" init-method="init">
<property name="getURL" value="${fss.client.getURL}" />
<property name="uploadURL" value="${fss.client.uploadURL}" />
<property name="listURL" value="${fss.client.listURL}" />
<property name="fssServerSites" value="${fss.client.serverSites}" />
<property name="badFssServerSitesCheckInterval" value="30" /><!-- unit:minute -->
</bean>

在需要上传、下载文件的地方调用bean fssClient的相关API即可。

2.4.2 非Spring方式

如果应用程序未使用到Spring框架，且不打算使用Spring，则通过如下程序获取fssClient：

FSSClient fssClient = FSSClientFactory.getFSSClient();

注意：请确保能访问到上文所述的配置文件。

=========================================================================================================

com.bill99.golden.inf.fss.client 
类 FSSClient

java.lang.Object

  com.bill99.golden.inf.fss.client.FSSClient

---

public class FSSClient

extends java.lang.Object

---

构造方法摘要

FSSClient() 
           

 

方法摘要

 boolean

deleteFile(java.lang.String appCode, java.lang.String fileId) 
          删除FSS上的文件

 void

downloadFile(java.lang.String appCode, java.lang.String fileId, java.io.OutputStream output) 
          下载指定的文件

 void

downloadFile(java.lang.String appCode, java.lang.String fileId, java.io.OutputStream output, java.lang.Integer timeout) 
          下载指定的文件

 void

fssGetFile(java.lang.String appCode, java.lang.String fileId, HttpServletResponse resp) 
          已过时。 use downloadFile(String,String, OutputStream) or downloadFile(String,String, OutputStream, Integer) or #getFileContent(String,String)

 void

fssGetFile(java.lang.String appCode, java.lang.String fileId, java.lang.String localFilePath) 
          已过时。 use downloadFile(String, String, OutputStream) or downloadFile(String,String, OutputStream, Integer) or #getFileContent(String,String)

 java.lang.String

fssUploadFile(java.lang.String appCode, java.io.InputStream input, java.lang.String fileName) 
          已过时。 use #putFileContent(byte[], TimeUnit, long) or #uploadFile(InputStream, TimeUnit, long)#uploadFile(InputStream, TimeUnit, long, Integer)

 java.lang.String

fssUploadFile(java.lang.String appCode, java.lang.String localFilePath) 
          已过时。 use #putFileContent(byte[], TimeUnit, long) or #uploadFile(InputStream, TimeUnit, long)#uploadFile(InputStream, TimeUnit, long, Integer)

 byte[]

getFileContent(java.lang.String appCode, java.lang.String fileId, java.lang.Integer timeout) 
          下载指定的文件

 java.lang.String

putFileContent(java.lang.String appCode, byte[] content, java.lang.String fileName, java.util.concurrent.TimeUnit fileExpireTimeUnit, long fileExpireTime, java.lang.Integer timeout) 
          文件内容上传FSS

 void

setHttpServerTimeOut(int httpServerTimeOut) 
          定义连接超时时间

 void

setHttpSocketTimeOut(int httpSocketTimeOut) 
          定义读取超时时间

 java.lang.String

uploadFile(java.lang.String appCode, java.io.InputStream input, java.lang.String fileName, java.util.concurrent.TimeUnit fileExpireTimeUnit, long fileExpireTime) 
          文件流上传至FSS

 java.lang.String

uploadFile(java.lang.String appCode, java.io.InputStream input, java.lang.String fileName, java.util.concurrent.TimeUnit fileExpireTimeUnit, long fileExpireTime, java.lang.Integer timeout) 
          文件流上传至FSS

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

FSSClient

public FSSClient()

方法详细信息

setHttpServerTimeOut

public void setHttpServerTimeOut(int httpServerTimeOut)

定义连接超时时间

参数：

httpServerTimeOut -

---

setHttpSocketTimeOut

public void setHttpSocketTimeOut(int httpSocketTimeOut)

定义读取超时时间

参数：

httpSocketTimeOut -

---

fssGetFile

@Deprecated

public void fssGetFile(java.lang.String appCode,

                                  java.lang.String fileId,

                                  java.lang.String localFilePath)

                throws java.lang.Exception

已过时。 use downloadFile(String, String, OutputStream) or downloadFile(String,String, OutputStream, Integer) or#getFileContent(String,String)

从FSS下载文件，并且存储到本地路径

参数：

appCode - 调用者的应用的名字

fileId - 文件的id，在上传的时候生成，客户端需要在上传成功后保存这个id

localFilePath - 本地文件路径

抛出：

Exception,如果文件找不到，会throw - Exception

java.lang.Exception

---

fssGetFile

@Deprecated

public void fssGetFile(java.lang.String appCode,

                                  java.lang.String fileId,

                                  HttpServletResponse resp)

                throws java.lang.Exception

已过时。 use downloadFile(String,String, OutputStream) or downloadFile(String,String, OutputStream, Integer) or#getFileContent(String,String)

从FSS下载文件，并且返回给web下载

参数：

appCode - 调用者的应用的名字

fileId - 文件的id，在上传的时候生成，客户端需要在上传成功后保存这个id

resp - web请求的响应

抛出：

Exception,如果文件找不到，会throw - Exception

java.lang.Exception

---

fssUploadFile

@Deprecated

public java.lang.String fssUploadFile(java.lang.String appCode,

                                                 java.lang.String localFilePath)

                               throws java.lang.Exception

已过时。 use #putFileContent(byte[], TimeUnit, long) or #uploadFile(InputStream, TimeUnit, long) #uploadFile(InputStream, TimeUnit, long, Integer)

把本地文件上传到FSS存储上

参数：

appCode - 调用者的应用的名字

localFilePath - 本地文件路径

返回：

fileId 文件的Id，客户端需要存储这个id，以后下载该文件的时候需要这个id

抛出：

java.lang.Exception

---

fssUploadFile

@Deprecated

public java.lang.String fssUploadFile(java.lang.String appCode,

                                                 java.io.InputStream input,

                                                 java.lang.String fileName)

                               throws java.lang.Exception

已过时。 use #putFileContent(byte[], TimeUnit, long) or #uploadFile(InputStream, TimeUnit, long) #uploadFile(InputStream, TimeUnit, long, Integer)

把本地文件上传到FSS存储上

参数：

appCode - 调用者的应用的名字

input - 需要上传的文件流

fileName - 需要上传的文件名

返回：

fileId 文件的Id，客户端需要存储这个id，以后下载该文件的时候需要这个id

抛出：

java.lang.Exception

---

uploadFile

public java.lang.String uploadFile(java.lang.String appCode,

                                   java.io.InputStream input,

                                   java.lang.String fileName,

                                   java.util.concurrent.TimeUnit fileExpireTimeUnit,

                                   long fileExpireTime)

                            throws java.lang.Exception

文件流上传至FSS

参数：

input - 上传的文件流

fileExpireTimeUnit - 有效期的时间单位

fileExpireTime - 从现在开始计算，文件的有效期 , 0 and negative value - means no expiration

timeout - 默认3min

返回：

抛出：

java.lang.Exception

从以下版本开始：

4.3.45.1

---

uploadFile

public java.lang.String uploadFile(java.lang.String appCode,

                                   java.io.InputStream input,

                                   java.lang.String fileName,

                                   java.util.concurrent.TimeUnit fileExpireTimeUnit,

                                   long fileExpireTime,

                                   java.lang.Integer timeout)

                            throws java.lang.Exception

文件流上传至FSS

参数：

input - 上传的文件流

fileExpireTimeUnit - 有效期的时间单位

fileExpireTime - 从现在开始计算，文件的有效期 , 0 and negative value - means no expiration

timeout - defines the socket timeout in milliseconds, 定义socket超时,单位毫秒

返回：

抛出：

java.lang.Exception

从以下版本开始：

4.3.45.1

---

putFileContent

public java.lang.String putFileContent(java.lang.String appCode,

                                       byte[] content,

                                       java.lang.String fileName,

                                       java.util.concurrent.TimeUnit fileExpireTimeUnit,

                                       long fileExpireTime,

                                       java.lang.Integer timeout)

                                throws java.lang.Exception

文件内容上传FSS

参数：

input - 上传的文件流

fileExpireTimeUnit - 有效期的时间单位

fileExpireTime - 从现在开始计算，文件的有效期 , 0 and negative value - means no expiration

timeout - defines the socket timeout in milliseconds, 定义socket超时,单位毫秒

返回：

抛出：

java.lang.Exception

---

getFileContent

public byte[] getFileContent(java.lang.String appCode,

                             java.lang.String fileId,

                             java.lang.Integer timeout)

                      throws java.lang.Exception

下载指定的文件

参数：

fileId - 要下载的文件

timeout - 定义socket超时,单位毫秒

返回：

文件内容

抛出：

java.lang.Exception

从以下版本开始：

4.3.45.1

---

downloadFile

public void downloadFile(java.lang.String appCode,

                         java.lang.String fileId,

                         java.io.OutputStream output)

                  throws java.lang.Exception

下载指定的文件

参数：

fileId - 要下载的文件

output - 要写入数据的数据流

抛出：

java.lang.Exception

从以下版本开始：

4.3.45.1

---

downloadFile

public void downloadFile(java.lang.String appCode,

                         java.lang.String fileId,

                         java.io.OutputStream output,

                         java.lang.Integer timeout)

                  throws java.lang.Exception

下载指定的文件

参数：

fileId - 要下载的文件

output - 要写入数据的数据流

timeout - 定义socket超时,单位毫秒

抛出：

java.lang.Exception - *

从以下版本开始：

4.3.45.1

---

deleteFile

public boolean deleteFile(java.lang.String appCode,

                          java.lang.String fileId)

                   throws java.lang.Exception

删除FSS上的文件

参数：

fileId - 指定要删除的文件

返回：

成功true,失败false

抛出：

java.lang.Exception - *

直接通过URL下载

http://192.168.64.39:8085/fss-server/FileDownload?appCode=forgetpwd&fileId=d6db9bcd-f73c-49c0-b6bb-9c35cfdd03fc