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

偏执的太偏执、 2022-02-22 10:56 189阅读 0赞

## 用例 ##

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

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

这操作可能需要大量的时间，所以我们需要显示进度。这意味着我们不能阻塞触发操作的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($taskId))

查看[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($renameJobStatusJSON)  
\#end  
\{ \{/velocity\}\}

# 客户端控制器 #

在客户端，JavaScript代码负责：

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

# 一般流程 #

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMzODczNDMx_size_16_color_FFFFFF_t_70][]

[Job Module]: http://extensions.xwiki.org/xwiki/bin/view/Extension/Job+Module
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMzODczNDMx_size_16_color_FFFFFF_t_70]: /images/20220222/90039683f288435a80cca866b85f90a5.png