xwiki开发者指南-执行异步任务

用例

实现对空间重命名，需要考虑到以下问题：

• 一个空间可以有很多页面
• 每个页面可以有很多反向链接
• 一些页面可以有大量的内容，我们要在内容里更新相对链接

这操作可能需要大量的时间，所以我们需要显示进度。这意味着我们不能阻塞触发操作的HTTP请求。换句话说，操作应该是异步的。

API设计

在我们开始实现之前，我们需要设计重命名API。实现异步任务的主要方法有2种：

1. push: 启动任务，然后等待通知任务进度，成功或失败。为了得到通知，可以：
   • 无论是传递一个回调(callback)给API
   • 或者API返回一个promise，你可以使用一个注册的回调
2. pull: 启动任务，然后你定时ask for updates直到任务完成（成功或失败）。在这种情况下，API需要提供一些方法来访问任务的状态

第一个选项（push）是很好的，但它需要触发任务代码和执行任务代码之间的双向连接。这是不符合（标准）的HTTP协议，服务端（通常）是不会把数据推送到客户端。客户端是可以从服务器拉数据。因此，我们要使用第二个选项。

## Start the task. #set (taskId = services.space.rename(spaceReference, newSpaceName)) ... ## Pull the task status. #set (taskStatus = services.space.getRenameStatus(

查看Job Module了解如何实现此API。

Request(请求)

request表示该任务的输入。这包括：

• 任务所需要的数据(例如空间引用和新的空间名称)
• 上下文信息（例如触发任务的用户）
• 任务配置选项。 例如：
  • 是否检查访问权限
  • 任务是否是交互的（在任务执行过程中可能需要用户输入）

每一个请求都有一个用来访问任务状态的标识符。

public class RenameRequest extends org.xwiki.job.AbstractRequest { private static final String PROPERTY_SPACE_REFERENCE = "spaceReference"; private static final String PROPERTY_NEW_SPACE_NAME = "newSpaceName"; private static final String PROPERTY_CHECK_RIGHTS = "checkrights"; private static final String PROPERTY_USER_REFERENCE = "user.reference"; public SpaceReference getSpaceReference() { return getProperty(PROPERTY_SPACE_REFERENCE); } public void setSpaceReference(SpaceReference spaceReference) { setProperty(PROPERTY_SPACE_REFERENCE, spaceReference); } public String getNewSpaceName() { return getProperty(PROPERTY_NEW_SPACE_NAME); } public void setNewSpaceName(String newSpaceName) { setProperty(PROPERTY_NEW_SPACE_NAME, newSpaceName); } public boolean isCheckRights() { return getProperty(PROPERTY_CHECK_RIGHTS, true); } public void setCheckRights(boolean checkRights) { setProperty(PROPERTY_CHECK_RIGHTS, checkRights); } public DocumentReference getUserReference() { return getProperty(PROPERTY_USER_REFERENCE); } public void setUserReference(DocumentReference userReference) { setProperty(PROPERTY_USER_REFERENCE, userReference); } }

Questions(询问)

正如我们所提到的，在作业执行过程中，作业可以通过asking questions进行互动。例如，如果已经有一个空间与新的空间名称重复，那么我们就必须决定是否：

• 停止重命名
• 或合并两个空间

如果我们决定合并两个空间，则有可能在两个空间有一样名字的文档，在这种情况下，我们必须决定是否覆盖目标文档。

为了让这个例子简单点，我们始终合并这两个空间，但我们会要求用户确认是否覆盖。

public class OverwriteQuestion { private final DocumentReference source; private final DocumentReference destination; private boolean overwrite = true; private boolean askAgain = true; public OverwriteQuestion(DocumentReference source, DocumentReference destination) { this.source = source; this.destination = destination; } public EntityReference getSource() { return source; } public EntityReference getDestination() { return destination; } public boolean isOverwrite() { return overwrite; } public void setOverwrite(boolean overwrite) { this.overwrite = overwrite; } public boolean isAskAgain() { return askAgain; } public void setAskAgain(boolean askAgain) { this.askAgain = askAgain; } }

Job Status(作业状态)

提供作业状态，默认情况下，访问：

• 作业状态(例如 NONE, RUNNING, WAITING, FINISHED)
• 作业请求
• 作业日志 ("INFO: Document X.Y has been renamed to A.B")
• 作业进展 (72%完成)

大多数时候，你并不需要扩展作业模块提供的DefaultJobStatus，除非你想存储：

• 更多进展的信息（例如已到目前为止改名的文件清单）
• 任务结果/输出

请注意，请求和作业状态必须是可序列化，所以要小心你在自定义作业状态存储什么样信息。例如，对于任务输出，可能在输出存储一个引用，路径或URL更好而不是存储输出本身。

作业状态也是job沟通通道：

• 如果作业发起一个询问，我们
  • 从作业状态访问询问(question)
  • 通过作业状态答复询问
• 如果你想取消的作业必须通过作业状态来执行

public class RenameJobStatus extends DefaultJobStatus<RenameRequest> { private boolean canceled; private List<DocumentReference> renamedDocumentReferences = new ArrayList<>(); public RenameJobStatus(RenameRequest request, ObservationManager observationManager, LoggerManager loggerManager, JobStatus parentJobStatus) { super(request, observationManager, loggerManager, parentJobStatus); } public void cancel() { this.canceled = true; } public boolean isCanceled() { return this.canceled; } public List<DocumentReference> getRenamedDocumentReferences() { return this.renamedDocumentReferences; } }

脚本服务

现在，我们需要实现一个ScriptService，使用Velocity触发重命名，并得到重命名状态。

@Component @Named(SpaceScriptService.ROLE_HINT) @Singleton public class SpaceScriptService implements ScriptService { public static final String ROLE_HINT = "space"; public static final String RENAME = "rename"; @Inject private JobExecutor jobExecutor; @Inject private JobStatusStore jobStatusStore; @Inject private DocumentAccessBridge documentAccessBridge; public String rename(SpaceReference spaceReference, String newSpaceName) { setError(null); RenameRequest renameRequest = createRenameRequest(spaceReference, newSpaceName); try { this.jobExecutor.execute(RENAME, renameRequest); List<String> renameId = renameRequest.getId(); return renameId.get(renameId.size() - 1); } catch (Exception e) { setError(e); return null; } } public RenameJobStatus getRenameStatus(String renameJobId) { return (RenameJobStatus) this.jobStatusStore.getJobStatus(getJobId(renameJobId)); } private RenameRequest createRenameRequest(SpaceReference spaceReference, String newSpaceName) { RenameRequest renameRequest = new RenameRequest(); renameRequest.setId(getNewJobId()); renameRequest.setSpaceReference(spaceReference); renameRequest.setNewSpaceName(newSpaceName); renameRequest.setInteractive(true); renameRequest.setCheckRights(true); renameRequest.setUserReference(this.documentAccessBridge.getCurrentUserReference()); return renameRequest; } private List<String> getNewJobId() { return getJobId(UUID.randomUUID().toString()); } private List<String> getJobId(String suffix) { return Arrays.asList(ROLE_HINT, RENAME, suffix); } }

Job实现

Jobs是个组件。让我们来看看我们如何能够实现它们。

@Component @Named(SpaceScriptService.RENAME) public class RenameJob extends AbstractJob<RenameRequest, RenameJobStatus> implements GroupedJob { @Inject private AuthorizationManager authorization; @Inject private DocumentAccessBridge documentAccessBridge; private Boolean overwriteAll; @Override public String getType() { return SpaceScriptService.RENAME; } @Override public JobGroupPath getGroupPath() { String wiki = this.request.getSpaceReference().getWikiReference().getName(); return new JobGroupPath(Arrays.asList(SpaceScriptService.RENAME, wiki)); } @Override protected void runInternal() throws Exception { List<DocumentReference> documentReferences = getDocumentReferences(this.request.getSpaceReference()); this.progressManager.pushLevelProgress(documentReferences.size(), this); try { for (DocumentReference documentReference : documentReferences) { if (this.status.isCanceled()) { break; } else { this.progressManager.startStep(this); if (hasAccess(Right.DELETE, documentReference)) { move(documentReference, this.request.getNewSpaceName()); this.status.getRenamedDocumentReferences().add(documentReference); this.logger.info("Document [{}] has been moved to [{}].", documentReference, this.request.getNewSpaceName()); } } } } finally { this.progressManager.popLevelProgress(this); } } private boolean hasAccess(Right right, EntityReference reference) { return !this.request.isCheckRights() || this.authorization.hasAccess(right, this.request.getUserReference(), reference); } private void move(DocumentReference documentReference, String newSpaceName) { SpaceReference newSpaceReference = new SpaceReference(newSpaceName, documentReference.getWikiReference()); DocumentReference newDocumentReference = documentReference.replaceParent(documentReference.getLastSpaceReference(), newSpaceReference); if (!this.documentAccessBridge.exists(newDocumentReference) || confirmOverwrite(documentReference, newDocumentReference)) { move(documentReference, newDocumentReference); } } private boolean confirmOverwrite(DocumentReference source, DocumentReference destination) { if (this.overwriteAll == null) { OverwriteQuestion question = new OverwriteQuestion(source, destination); try { this.status.ask(question); if (!question.isAskAgain()) { // Use the same answer for the following overwrite questions. this.overwriteAll = question.isOverwrite(); } return question.isOverwrite(); } catch (InterruptedException e) { this.logger.warn("Overwrite question has been interrupted."); return false; } } else { return this.overwriteAll; } } }

服务端控制器

我们需要从JavaScript能够触发重命名操作和远程定时获得状态更新。这意味着重命名API应该可以通过一些URL访问：

• ?action=rename -> redirects to ?data=jobStatus
• ?data=jobStatus&jobId=xyz -> return the job status serialized as JSON
• ?action=continue&jobId=xyz -> redirects to ?data=jobStatus
• ?action=cancel&jobId=xyz -> redirects to ?data=jobStatus

{{velocity}} #if (request.action == 'rename') #set (spaceReference = services.model.resolveSpace(request.spaceReference)) #set (renameJobId = services.space.rename(spaceReference, request.newSpaceName)) response.sendRedirect(doc.getURL('get', escapetool.url({ 'outputSyntax': 'plain', 'jobId': renameJobId }))) #elseif (request.action == 'continue') #set (renameJobStatus = services.space.getRenameStatus(request.jobId)) #set (overwrite = request.overwrite == 'true') #set (discard = renameJobStatus.question.setOverwrite(overwrite)) #set (discard = renameJobStatus..answered()) #elseif (request.action == 'cancel') #set (renameJobStatus = services.space.getRenameStatus(request.jobId)) #set (discard = renameJobStatus.cancel()) response.sendRedirect(doc.getURL('get', escapetool.url({ 'outputSyntax': 'plain', 'jobId': renameJobId }))) #elseif (request.data == 'jobStatus') #set (renameJobStatus = services.space.getRenameStatus(request.jobId)) #buildRenameStatusJSON(renameJobStatus) response.setContentType('application/json') jsontool.serialize(

客户端控制器

在客户端，JavaScript代码负责：

• 通过一个AJAX请求到服务端控制器触发任务
• 定时检索任务状态更新和更新显示进度
• 向用户传递job询问和传递用户的答复到服务端控制器

var onStatusUpdate = function(status) { updateProgressBar(status); if (status.state == 'WAITING') { // Display the question to the user. displayQuestion(status); } else if (status.state != 'FINISHED') { // Pull task status update. setTimeout(function() { requestStatusUpdate(status.request.id).success(onStatusUpdate); }, 1000); } }; // Trigger the rename task. rename(parameters).success(onStatusUpdate); // Continue the rename after the user answers the question. continueRename(parameters).success(onStatusUpdate); // Cancel the rename. cancelRename(parameters).success(onStatusUpdate);

一般流程