DocConvertService (文档转换工具包 0.0.3-SNAPSHOT API)

java.lang.Object
- com.kdgcsoft.power.doc.convert.DocConvertService

```
public class DocConvertService
extends Object
```
文档转换工具。调用外部程序，把office等所支持的文档格式转换为PDF等格式。多线程执行，支持同步、异步调用。
转换后文件存放在工作目录下，可通过转换时返回的key作为参数，调用接口获取。
源文件与key的映射记录可从日志文件中获取。建议在日志配置文件中给名为"ConvertHistory"的 Logger定义专门的输出文件位置，这样记录所有文件对应关系，便于维护查错。

构造器概要

构造器
构造器和说明

DocConvertService()

构造器
构造器和说明
`DocConvertService()`

方法概要

方法
限定符和类型	方法和说明
`static File`	`addConvertTask(File srcFile, File targetDir, OutputType outType, boolean isAsync)` 添加一个转换任务到转换队列，并根据参数决定是同步等待任务完成还是立即返回
`static String`	`convert(File srcFile, OutputType outType, boolean isAsync)` 转换文档，可指定使用异步模式还是同步模式。
`static String`	`convert(File srcFile, String key, OutputType outType)` 使用同步方式转换文档。
`static String`	`convert(File srcFile, String key, OutputType outType, boolean isAsync)` 执行转换过程。
`static String`	`convert(InputStream inputStream, String srcFileName, OutputType outType, boolean isAsync)` 转换文件流到文档，可指定使用异步模式还是同步模式。
`static String`	`convert(InputStream inputStream, String srcFileName, String key, OutputType outType)` 使用同步方式转换文档。
`static String`	`convert(InputStream inputStream, String srcFileName, String key, OutputType outType, boolean isAsync)` 执行转换过程。
`static void`	`deleteConvertedFileQuietly(String key)` 在转换存储库中删除指定key的文件，包括所有格式。
`static File`	`findLockFile(String key, OutputType outType)` 查找某个转换任务的锁文件。
`static void`	`finish()` 关闭外部转换进程。
`static File`	`getConvertedFile(String key, OutputType outType)` 获取转换后的文件。
`static InputStream`	`getConvertedFileAsStream(String key, OutputType outType)` 获取转换后的完整文档数据流。
`static File`	`getConvertedPage(String key, OutputType outType, int page)` 按页获取转换后的文件。
`static InputStream`	`getConvertedPageAsStream(String key, OutputType outType, int page)` 按页获取转换后的文件数据流。
`static File`	`getConvertedPng(String key, int page)` 按页获取转换后的png图片文件。
`static InputStream`	`getConvertedPngAsStream(String key, int page)` 按页获取转换后的png图片数据流。
`static int`	`getPageCount(String key)` 获取文档的页数。
`static void`	`init(DocConvertSettings settings)` 初始化转换环境
`static boolean`	`isConverting(String key, OutputType outType)` 判断某个转换任务是否正在进行
`static void`	`redoUnfinished()` 重新执行未完成的文档转换。
`static void`	`waitConvert(String key, OutputType outType)` 如果转换任务存在，则等待转换任务完成，否则直接返回。

从类继承的方法 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 构造器详细资料
  - DocConvertService
```
public DocConvertService()
```
- 方法详细资料
  - init
```
public static void init(DocConvertSettings settings)
                 throws IOException
```
    初始化转换环境
    
    参数:
    settings - 转换设定
    
    抛出:
    
    IOException
  - finish
```
public static void finish()
```
    关闭外部转换进程。应在系统退出时调用。如果需要再次启动转换进程，要重新调用init()。
  - redoUnfinished
```
public static void redoUnfinished()
```
    重新执行未完成的文档转换。主要用于程序终止、机器断电等异常情况下的后处理。该函数会检查工作目录下的incoming文件夹，当发现有符合要求的未完成转换的文件时(通过任务定义文件：[文件Key].[源文件扩展名].[OutputType].task)，即将其重新投入队列进行转换。
    需要在调用init(DocConvertSettings)之后调用本函数。调用过程是安全的，如果不存在异常终止的转换任务，则什么都不会做。
  - convert
```
public static String convert(File srcFile,
             OutputType outType,
             boolean isAsync)
                      throws DocConvertException
```
    转换文档，可指定使用异步模式还是同步模式。
    
    参数:
    srcFile - 源文档
    outType - 输出类型枚举
    isAsync - 是否异步
    
    返回:
    用于获取转换结果文件的Key
    
    抛出:
    
    DocConvertException
  - convert
```
public static String convert(InputStream inputStream,
             String srcFileName,
             OutputType outType,
             boolean isAsync)
                      throws DocConvertException
```
    转换文件流到文档，可指定使用异步模式还是同步模式。
    
    参数:
    inputStream - 源文件流
    srcFileName - 源文件名。因为仅根据文件流无法识别源文件格式，所以转化器需要依赖文件名参数。只要扩展名正确即可，主文件名不使用。
    outType - 输出类型枚举
    isAsync - 是否异步
    
    返回:
    用于获取转换结果文件的Key
    
    抛出:
    
    DocConvertException
  - convert
```
public static String convert(File srcFile,
             String key,
             OutputType outType)
                      throws DocConvertException
```
    使用同步方式转换文档。参数中直接指定文档的key(必须与当前StorageHelper使用的key格式一致），返回的是相同key。用于文档更新、REDO。当外部调用者本身使用key管理文档时可采用此种转换方式，便于保持一致，避免系统中存在多种key。也可用于文档更新（key不变，只重新转换）。
    
    参数:
    srcFile - 源文档
    key - 指定使用的文件Key，用于存储管理
    
    返回:
    用于获取转换结果文件的key
    
    抛出:
    
    DocConvertException
  - convert
```
public static String convert(InputStream inputStream,
             String srcFileName,
             String key,
             OutputType outType)
                      throws DocConvertException
```
    使用同步方式转换文档。参数中直接指定文档的key(必须与当前StorageHelper使用的key格式一致）。用于文档更新、REDO。
    
    参数:
    inputStream - 源文档流
    srcFileName - 源文件名。因为仅根据文件流无法识别源文件格式，所以转化器需要依赖文件名参数。只要扩展名正确即可，主文件名不使用。
    key - 存储key
    
    返回:
    用于获取转换结果文件的key
    
    抛出:
    
    DocConvertException
  - convert
```
public static String convert(File srcFile,
             String key,
             OutputType outType,
             boolean isAsync)
                      throws DocConvertException
```
    执行转换过程。此过程通过线程池执行转换任务，并根据是否异步的参数决定是启动任务后立即返回还是等待任务执行完毕再返回。
    
    参数:
    srcFile - 源文档
    key - 指定使用的文件Key。应用端第一次转换某文件时不要指定Key，但需要记录转换器返回的Key。下次转换相同文件时则应传入该Key，便于转换器识别是否是曾经转换过的文件
    outType - 要转换成的类型
    isAsync - 是否异步
    
    返回:
    用于获取转换结果文件的key
    
    抛出:
    
    DocConvertException
  - addConvertTask
```
public static File addConvertTask(File srcFile,
                  File targetDir,
                  OutputType outType,
                  boolean isAsync)
                           throws DocConvertException
```
    添加一个转换任务到转换队列，并根据参数决定是同步等待任务完成还是立即返回
    
    参数:
    srcFile - 待转换的源文件
    targetDir - 转换后存放的目标目录
    outType - 要转换成的类型
    isAsync - 是否异步执行。true：异步执行，函数立即返回 false：函数将等待转换任务完成再返回
    
    返回:
    同步执行：如果转换后是单个文件（不分页），则返回文件对象，否则返回分页文件所在的目录对象;
    异步执行：返回null
    
    抛出:
    
    DocConvertException - 转换时出现异常
  - convert
```
public static String convert(InputStream inputStream,
             String srcFileName,
             String key,
             OutputType outType,
             boolean isAsync)
                      throws DocConvertException
```
    执行转换过程。此过程通过线程池执行转换任务，并根据是否异步的参数决定是启动任务后立即返回还是等待任务执行完毕再返回。
    
    参数:
    inputStream - 源文档
    srcFileName - 源文件名。因为仅根据文件流无法识别源文件格式，所以转化器需要依赖文件名参数。只要扩展名正确即可，主文件名不使用。
    key - 指定使用的文件存储Key
    isAsync - 是否异步
    
    返回:
    用于获取转换结果文件的key
    
    抛出:
    
    DocConvertException
  - getConvertedFile
```
public static final File getConvertedFile(String key,
                    OutputType outType)
```
    获取转换后的文件。如果文档正在转换，则函数会阻塞直到转换完成。如果指定格式的文档尚不存在，也不处于转换过程中，则返回null。
    如果要求的格式文件是单一文件，则返回文件对象；如果要求的格式文件是以分页形式存在的（例如png图片）则返回储存这些分页文件的子文件夹。
    调用者应该使用File.isFile()来判断返回的究竟是文件还是文件夹，再决定如何进行下一步处理。当前转换配置下，只有请求png图片时会返回一个文件夹对象，其他格式返回的都是文件对象。如果想要直接获取分片的文件，应使用另一个函数：getConvertedPage(String, OutputType, int)
    
    参数:
    key - 文档key。在转换时获得。
    outType - 要获取的文档类型（转换后的格式）
    
    返回:
    文档File对象。如果不存在或等待转换过程超时，返回null。
  - getConvertedFileAsStream
```
public static InputStream getConvertedFileAsStream(String key,
                                   OutputType outType)
```
    获取转换后的完整文档数据流。如果文档正在转换，则函数会阻塞直到转换完成。
    当转换后文档是分页保存的情况下，需要指定页面编号，使用 getConvertedPageAsStream(String, OutputType, int)
    
    参数:
    key - 文档key。在转换时获得。
    outType - 要获取的文档类型（转换后的格式）
    
    返回:
    文档Stream对象。如果不存在，返回null。
  - getConvertedPng
```
public static File getConvertedPng(String key,
                   int page)
```
    按页获取转换后的png图片文件。如果文档正在转换，则函数会阻塞直到转换完成。
    
    参数:
    key - 文档key
    page - 第几页。基于0
    
    返回:
    图片文件对象。如果不存在，返回null。
  - getConvertedPngAsStream
```
public static InputStream getConvertedPngAsStream(String key,
                                  int page)
```
    按页获取转换后的png图片数据流。如果文档正在转换，则函数会阻塞直到转换完成。
    
    参数:
    key - 文档key
    page - 第几页。基于0
    
    返回:
    图片文件流。如果不存在，返回null。
  - getConvertedPage
```
public static File getConvertedPage(String key,
                    OutputType outType,
                    int page)
```
    按页获取转换后的文件。通常用于图片，但如果转换器支持分页，也可以用于HTML等文件。如果文档正在转换，则函数会阻塞直到转换完成。
    
    参数:
    key - 文档key
    outType - 要获取的文件格式
    page - 第几页。基于0
    
    返回:
    图片文件对象。如果不存在，返回null。
  - getConvertedPageAsStream
```
public static InputStream getConvertedPageAsStream(String key,
                                   OutputType outType,
                                   int page)
```
    按页获取转换后的文件数据流。通常用于图片，但如果转换器支持分页，也可以用于HTML等文件。
    
    参数:
    key - 文档key
    outType - 要获取的文件格式
    page - 第几页。基于0
    
    返回:
    文件流。如果不存在，返回null。
  - getPageCount
```
public static int getPageCount(String key)
                        throws DocConvertException
```
    获取文档的页数。优先根据pdf文档的页数，如果pdf文件不存在，则把png图片文件夹下的png图片数量作为页数返回。在查找pdf或png文件时如果刚好正在进行该格式的文件转换，则会等待直到转换完成。如果pdf和png都不存在，且不在转换状态中，则返回-1。
    
    参数:
    key - 文档key
    
    返回:
    页数。如果找不到pdf文档或png文件夹，返回-1。
    
    抛出:
    
    DocConvertException - 读取PDF文件中的页数信息时发生异常
  - isConverting
```
public static boolean isConverting(String key,
                   OutputType outType)
```
    判断某个转换任务是否正在进行
    
    参数:
    key - 转换文件的key
    outType - 要转换的目标类型
    
    返回:
    是否正在进行转换，true: 正在转换
  - findLockFile
```
public static File findLockFile(String key,
                OutputType outType)
```
    查找某个转换任务的锁文件。如果存在锁文件，意味着该任务正在进行中。
    
    参数:
    key - 被转换的文件key
    outType - 转换目标类型
    
    返回:
    如果锁文件存在，则返回锁文件对象，否则返回null
  - waitConvert
```
public static void waitConvert(String key,
               OutputType outType)
                        throws TimeoutException
```
    如果转换任务存在，则等待转换任务完成，否则直接返回。
    具体方法是查看任务锁文件是否存在，如果存在则每隔100毫秒轮询一次，直到锁消失或等待超时（超过设定的转换超时时间）。如果不存在则直接返回。
    
    参数:
    key - 被转换的文件key
    outType - 转换目标类型
    
    抛出:
    
    TimeoutException - 如果等待超时，抛出异常
  - deleteConvertedFileQuietly
```
public static void deleteConvertedFileQuietly(String key)
```
    在转换存储库中删除指定key的文件，包括所有格式。
    
    参数:
    key - 文件key

类 DocConvertService

构造器概要

方法概要

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

构造器详细资料

DocConvertService

方法详细资料

init

finish

redoUnfinished

convert

convert

convert

convert

convert

addConvertTask

convert

getConvertedFile

getConvertedFileAsStream

getConvertedPng

getConvertedPngAsStream

getConvertedPage

getConvertedPageAsStream

getPageCount

isConverting

findLockFile

waitConvert

deleteConvertedFileQuietly