# 1 简介
文件服务是苍穹提供的文件服务API，也称之为FileService。提供文件上传、下载、预览、删除功能。
# 2 应用场景
主要应用于附件和图片的上传、下载、预览、删除。
# 3 接口说明
文件服务相关接口定义和实现存在于bos-fileservice-sdk-1.0.jar中。对于使用者来说只需要调用kd.bos.fileservice.FileServiceFactory类创建文件服务对象FileService，然后调用FileService对象的接口方法即可。
## 3.1 接口列表
***FileServiceFactory***
| 静态方法 | 说明 |
| - | - |
| getAttachmentFileService | 创建附件服务 |
| getImageFileService | 创建图片服务 |
***FileService***
| 方法 | 说明 |
| - | - |
| upload | 上传文件 |
| download | 下载文件 |
| batchDownload | 批量下载文件 |
| getInputStream | 获取文件流 |
| preview | 文件预览 |
| removePreview | 删除excel预览缓存 |
| delete | 删除文件 |
## 3.2 接口详情
### upload
+ **功能描述**
上传文件。
+ **方法**
```java
String upload(FileItem fileItem) // 单个文件上传
List<String> upload(FileItem[] fileItems) // 批量文件上传
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| fileItem | FileItem | 文件对象 |
+ **返回值**
返回文件下载URL，批量上传则返回文件下载URL列表。
+ **示例代码**
```java
FileService fs=FileServiceFactory.getAttachmentFileService();
String path = "/SYS/BASE/dev1212/test/testUpload.pptx";
FileItem file = new FileItem("testUpload.pptx",path,new FileInputStream("D:/testUpload.pptx"));
fi.setCreateNewFileWhenExists(true);
path= fs.upload(file);
```
### download
+ **功能描述**
下载文件。
+ **方法**
```java
void download(String path, OutputStream out, String userAgent) // 将文件写入输出流
void download(String path, HttpServletResponse servletResponse, String userAgent) // 将文件写入到HttpServletResponse的输出流ServletOutputStream中
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
| out | OutputStream | 文件输出流 |
| servletResponse | HttpServletResponse | HTTP响应对象 |
| userAgent | String | 用户代理字符串 |
+ **返回值**
无
+ **示例代码**
```java
FileService fs=FileServiceFactory.getAttachmentFileService();
String path = "/SYS/BASE/dev1212/test/testUpload.pptx";
String userAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36";
OutputStream out = null;
try {
out = new FileOutputStream("d:/testDownld.pptx");
} catch (FileNotFoundException e) {
e.printStackTrace();
}
fs.download(path,out,userAgent); // 将文件写入输出流
```
### batchDownload
+ **功能描述**
批量下载文件。
+ **方法**
```java
void batchDownload(BatchDownloadRequest request, OutputStream out, String userAgent);
void batchDownload(BatchDownloadRequest request, HttpServletResponse servletResponse, String userAgent);
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
| out | OutputStream | 文件输出流 |
| servletResponse | HttpServletResponse | HTTP响应对象 |
| userAgent | String | 用户代理字符串 |
+ **返回值**
无
+ **示例代码**
```java
FileService fs=FileServiceFactory.getAttachmentFileService();
String userAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36";
//test 目录
String testDirPathA = "/SYS/BASE/dev1212/test/a.pptx";
String testDirPathB = "/SYS/BASE/dev1212/test/b.pptx";
//temp 目录
String tempDirPathC = "/SYS/BASE/dev1212/temp/c.pptx";
String tempDirPathD = "/SYS/BASE/dev1212/temp/d.pptx";
//构造BatchDownloadRequest对象
Dir testDir = new Dir("test");
File aFile = new File("a.pptx", testDirPathA);
File bFile = new File("b.pptx", testDirPathB);
testDir.setFiles(new File[]{aFile,bFile});
Dir tempDir = new Dir("temp");
File cFile = new File("c.pptx", tempDirPathC);
File dFile = new File("d.pptx", tempDirPathD);
tempDir.setFiles(new File[]{cFile,dFile});
BatchDownloadRequest bdr = new BatchDownloadRequest("test-batch-download");
bdr.setDirs(new Dir[]{testDir,tempDir});
OutputStream out = null;
try {
out = new FileOutputStream("d:/test-batch-download.zip");
} catch (FileNotFoundException e) {
e.printStackTrace();
}
fs.batchDownload(bdr, OutputStream, userAgent);
```
### getInputStream
+ **功能描述**
获取文件流。
+ **方法**
```java
InputStream getInputStream(String path)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
+ **返回值**
获取文件流。
+ **示例代码**
```java
FileService fs=FileServiceFactory.getAttachmentFileService();
String path = "/SYS/BASE/dev1212/test/testUpload.pptx";
InputStream in = fs.getInputStream(path);
```
### preview
+ **功能描述**
文件预览。
+ **方法**
```java
Map<String,Object> preview(String fileName, String path,String userAgent)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
| fileName | String | 文件名 |
| userAgent | String | 用户代理字符串 |
+ **返回值**
返回<map, key>值为：<status, result>。调用预览接口，如果是word，ppt文件，Map的result返回pdf的InputStream；如果是excel文件，Map的result返回包含直接访问的url，id为key值的Map，通过url值直接访问预览excel，通过id删除excel预览缓存。
+ **示例代码**
```java
FileService fs=FileServiceFactory.getAttachmentFileService();
String path = "/SYS/BASE/dev1212/test/testUpload.pptx";
String userAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36";
Map<String,Object> result = fs.preview("testUpload.pptx", path, userAgent); // 此接口一般用于具体的预览服务中。
```
### removePreview
+ **功能描述**
删除excel预览缓存。（只有预览excel需要调用删除接口）
+ **方法**
```java
void removePreview(String id)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| id | String | 调用preview后返回的id |
+ **返回值**
无
+ **示例代码**
无
### delete
+ **功能描述**
删除文件。
+ **方法**
```java
void delete(String path)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| path | String | 文件路径 |
+ **返回值**
无
+ **示例代码**
```java
FileService fs=FileServiceFactory.getAttachmentFileService();
String path = "/SYS/BASE/dev1212/test/testUpload.pptx";
fs.delete(path);
```
