DigitalPlatform / dp2

Integrated Library System / 图书馆集成系统
http://digitalplatform.github.io/dp2
Apache License 2.0
106 stars 54 forks source link

dp2library API GetRes() 中获取文件 MD5 功能的用法 #893

Open DigitalPlatform opened 2 years ago

DigitalPlatform commented 2 years ago

dp2library API GetRes() 用于获取各种资源,包括数据库配置文件、数据库记录、dp2library 数据目录中的其它文件。

其中,有一个子功能,可以用来获取 dp2library 数据目录中一个文件的 MD5 hash 码。用法介绍如下:

用法1 一次请求获得 MD5

这是一种传统的用法,即用一次 GetRes() API 请求获得 MD5。但缺点是遇到尺寸很大的文件时,请求所用时间会很长,甚至会超过合理的超时时限。

请求时令参数 strStyle 内容中包含 "md5",返回时参数 baOutputTimestamp 中就是该文件的 MD5 码内容。注意,这样请求就无法同时获得文件的时间戳了。

用法2 任务方式获得 MD5

这种方式是用多次 GetRes() API 调用来获得 MD5,即先请求启动一个任务,然后不断请求查询这个任务的状态,一旦完成就停止查询。返回任务完成信息的那一次会返回 MD5。

这种方法的优点是没有超时的烦恼,但步骤较多,用法复杂一些。

步骤为:

1) 启动任务。请求时令参数 strStyle 内容中包含 "md5,beginTask",响应的 baOutputTimestamp 中会包含这个任务的 ID(UTF-8 方式的 byte[])。后面会用到这个 ID 查询任务状态; 2) 查询任务状态。请求时令参数 strStyle 内容中包含 "md5,getTaskResult,taskID:xxx",其中 xxx 需要用任务 ID 替换。若返回的 result.Value 为 0,表示任务还在进行、尚未完成(需要继续进行步骤 2) 直到探测到任务完成);若返回的 result.Value 为 1,表示任务已经完成(dp2library 服务器在本次 API 响应后会自动删除这个任务),并且 baOutputTimestamp 中即是 MD5 内容。

除了上述用法外,还有一些用法变体:

a) 启动任务时,可以由前端主动命名任务 ID。令参数 strStyle 内容包含 "md5,beginTask:xxx" 即可,其中 xxx 需要用任务 ID 替换。这样服务器就不用发生任务 ID 了,直接采用前端提供的任务 ID。注意,如果 dp2library 中已经存在一个这样 ID 的任务,操作前会自动取消和删除那个任务。

这样用法的好处是,令启动任务请求成为一个幂等的请求,如果遇到通讯失败,可以用刚才同样的任务 ID 重试请求,不会浪费任务 ID。而不包含 :xxx 参数的请求不是幂等的,如果启动任务请求遇到通讯故障失败,再要重试请求时,dp2library 服务器每次会重新发生一个任务 ID,前一次发生好的任务 ID 依然存在(任务还在继续执行)、并且无法被前端感知到(因为那一次响应时通讯失败了),这样多次请求会导致任务管理机制内被遗弃的任务信息无法正确删除。

b) 查询任务状态阶段,可以让 dp2library 服务器在任务完成的那一次响应不自动删除任务。令参数 strStyle 内容中包含 "md5,getTaskResult,dontRemove,taskID:xxx",注意其中 dontRemove 是新增加的参数。这样用法的好处是,令查询请求成为一个幂等的请求,如果遇到通讯失败,可以重试请求。而不包含 dontRemove 参数的请求不是幂等的,如果任务完成时的那一次查询请求遇到通讯故障失败,再要重试请求时,由于 dp2library 服务器一端已经自动删除了这个任务,会报错说任务不存在。

不过,这个用法需要再专门单独请求一次删除任务,令参数 strStyle 内容中包含 "md5,removeTask,taskID:xxx" 即可。(注,用 "md5,getTaskResult,taskID:xxx" 也可以达到同样目的)