# FileService简介

FileService是金蝶云苍穹提供的文件服务API，包括附件服务和图片服务，提供文件上传，下载，预览，删除功能。&nbsp;


##  创建FileService

- **创建附件服务**

```java
	FileService fs = FileServiceFactory.getAttachmentFileService();
```

 - **创建图片服务**

```java
	FileService fs = FileServiceFactory.getImageFileService();
```
&nbsp;**说明**：图片服务和文件服务的API是一致的，只是按存储的文件类型进行了服务区分，其中附件服务主要存储表单附件面板等相关文件，而图片服务主要存储用户头像信息，图片字段等图片文件。

##   API概览

| 方法                                                         | 功能                                   |
| :----------------------------------------------------------- | :------------------------------------- |
| String upload(FileItem fileItem)<br/>List<String> upload(FileItem[] fileItems)<br/> | 文件上传                            |
| void download(String path, OutputStream out, String userAgent);<br/>void download(String path, HttpServletResponse servletResponse, String userAgent);<br/>void batchDownload(BatchDownloadRequest request, OutputStream out, String userAgent);<br/>void batchDownload(BatchDownloadRequest request, HttpServletResponse servletResponse, String userAgent);<br/>InputStream getInputStream(String path); | 文件下载                             |
| Map<String,Object> preview(String fileName, String path,String userAgent); | 文件预览                            |
| void removePreview(String id);                | 删除预览缓存                          |
| public void delete(String path); | 删除文件                |



##   API详解

### 上传
- **String upload(FileItem fileItem);**
  &ensp;&ensp;FileItem：文件上传对象，通过String fileName（文件名）, String path（文件上传路径）, InputStream in（文件流）构造FileItem对象。上传返回文件下载url。

- **List<String> upload(FileItem[] fileItems);**
  &ensp;&ensp;批量文件上传接口。
  
  示例：
  
  ```java
  FileService fs=FileServiceFactory.getAttachmentFileService();
  String path = "/SYS/BASE/dev1212/test/testUpload.pptx";
  FileItem fi = new FileItem("testUpload.pptx",path,new FileInputStream("D:/testUpload.pptx"));
  fi.setCreateNewFileWhenExists(true);
  path= fs.upload(fi);
  ```


### 下载

- **void download(String path, OutputStream out, String userAgent);**
  &ensp;&ensp;通过path（文件路径），out(输出流)，userAgent(用户代理字符串)下载文件，该接口会将文件内容写入输出流OutputStream中。

- **void download(String path, HttpServletResponse servletResponse, String userAgent);**

  &ensp;&ensp;通过path（文件路径），servletResponse(输出流)，userAgent(用户代理字符串)下载文件，该接口会将文件内容写入HttpServletResponse 的输出流ServletOutputStream中。

- **InputStream getInputStream(String path);**
  &ensp;&ensp;通过path（文件路径）获得文件ImputStream。
  
  示例：
  
  ```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";
  /**
  * download by OutputStream
  */
  OutputStream out = null;
  		try {
  			out = new FileOutputStream("d:/testDownld.pptx");
  		} catch (FileNotFoundException e) {
  			e.printStackTrace();
  		}
  fs.download(path,out,userAgent);
  
  /**
  * getInputStream
  */
  InputStream in = fs.getInputStream(path);  
  
  ```
  
  

### 批量下载

- **void batchDownload(BatchDownloadRequest request, OutputStream out, String userAgent);**

  &ensp;&ensp;批量下载请求，将一批文件url下载为一个压缩包，写入OutputStream。

- **void batchDownload(BatchDownloadRequest request, HttpServletResponse servletResponse, String userAgent);**

  &ensp;&ensp;批量下载请求，将一批文件url下载为一个压缩包，写入HttpServletResponse 的输出流ServletOutputStream。
  
  
  
  示例：
  
  ```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});
  
  
  /**
  * batchDownload by OutputStream
  */
  OutputStream out = null;
  		try {
  			out = new FileOutputStream("d:/test-batch-download.zip");
  		} catch (FileNotFoundException e) {
  			e.printStackTrace();
  		}
  fs.batchDownload(bdr, OutputStream, userAgent);
  
  ```
  
  
  


### 预览
- **Map<String,Object> preview(String fileName, String path,String userAgent);**
  &ensp;&ensp;返回map key值为：status，result。调用预览接口，如果是word，ppt文件，Map的result返回pdf的InputStream；如果是excel文件，Map的result返回包含直接访问的url，id为key值的Map，通过url值直接访问预览excel，通过id删除excel预览缓存。
  
- **void removePreview(String id);**

   需要调用removePreview接口删除excel预览缓存。（只有预览excel需要调用删除接口）

### 删除
- **public void delete(String path);** 
  &ensp;&ensp;文件删除接口。
  
  示例：
  
  ```java
  FileService fs=FileServiceFactory.getAttachmentFileService();
  String path = "/SYS/BASE/dev1212/test/testUpload.pptx";
  fs.delete(path);
  ```

# 临时文件
##  简介

用户需要上传一些非持久性文件，在上传使用后需要文件在指定时间后失效，临时文件缓存用于存储具有失效时间的文件，通过TempFileCache接口进行临时文件操作。

##  创建TempFileCache
```java
TempFileCache tempfile = CacheFactory.getCommonCacheFactory().getTempFileCache();
```

##  示例

 ```java
		/**
		 * save
		 */
		TempFileCache tfc = CacheFactory.getCommonCacheFactory().getTempFileCache();
		int timeout = 60*60*2;//超时时间2小时
		InputStream in = null;
		try {
			 in = new FileInputStream("d:/temp.pptx");
		} catch (FileNotFoundException e) {
			e.printStackTrace();
		}
		String url = tfc.saveAsUrl("temp.pptx", in, timeout);
		
		/**
		 * getInputStream 
		 */
		InputStream tempIn = tfc.getInputStream(url);
		
		/**
		 * remove 
		 */
		tfc.remove(url);
 ```