wrench_orangeProvides APIs to refactor XWiki entities
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

7.2M1+

Description

This module provides APIs to perform various refactoring operations, such as move, copy, rename, delete, that target XWiki Entities. Since most of these operations can take a long time (e.g. renaming a space with lots of documents in it) they have been implemented as jobs that run in background threads for which we can monitor the process.

You can trigger the refactoring jobs from a Java component using the Job Executor or from Velocity/Groovy using the script service. Note that some jobs (like move) are interactive and thus can ask questions (e.g. whether you want to overwrite an existing document or not).

Script Service

For the sake of brevity in the following examples the HTTP request is blocked until the job is done by calling join(). In real life you should monitor the progress of the operation using the job status.

  • Copy a Space
    #set ($source = $services.model.resolveSpace('Path.To.Source'))
    #set ($destination = $services.model.resolveSpace('Path.To.New.Parent'))
    $services.refactoring.copy($source, $destination).join()
  • Copy a Space As
    #set ($source = $services.model.resolveSpace('Path.To.Source'))
    #set ($destination = $services.model.resolveSpace('Path.To.New.Name'))
    $services.refactoring.copyAs($source, $destination).join()
  • Move a Space
    #set ($source = $services.model.resolveSpace('Path.To.Source'))
    #set ($destination = $services.model.resolveSpace('Path.To.New.Parent'))
    $services.refactoring.move($source, $destination).join()
  • Move a Document
    #set ($source = $services.model.resolveDocument('Path.To.Source.WebHome'))
    #set ($destination = $services.model.resolveSpace('Path.To.New.Parent'))
    $services.refactoring.move($source, $destination).join()
  • Rename a Space
    #set ($source = $services.model.resolveSpace('Path.To.Source'))
    $services.refactoring.rename($source, 'NewName').join()
  • Rename a Document and set up a redirect from the old location to the new location
    #set ($source = $services.model.resolveDocument('Path.To.Source.WebHome'))
    $services.refactoring.rename($source, 'NewName').join()
  • Rename a Document without setting up a redirect from the old location to the new location
    #set ($source = $services.model.resolveDocument('Path.To.Source.WebHome'))
    #set ($renameRequest = $services.refactoring.requestFactory.createRenameRequest($source, 'NewName'))
    #set ($discard = $renameRequest.setAutoRedirect(false))
    $services.refactoring.rename($renameRequest)).join()
Before XWiki 10.11RC1 the function to create requests were attached to the refactoring service itself.
So to create the rename request before this version, you should use:
#set ($renameRequest = $services.refactoring.createRenameRequest($source, 'NewName')) 
  • Delete a Document
    #set ($source = $services.model.resolveDocument('Path.To.Source.WebHome'))
    $services.refactoring.delete($source).join()
  • Delete a Space
    #set ($source = $services.model.resolveSpace('Path.To.Source'))
    $services.refactoring.delete($source).join()
  • Convert a Terminal Document to a Nested Document
    #set ($source = $services.model.resolveDocument('Path.To.Page'))
    $services.refactoring.convertToNestedDocument($source).join()
  • Convert a Nested Document to a Terminal Document
    #set ($source = $services.model.resolveDocument('Path.To.Source.WebHome'))
    $services.refactoring.convertToTerminalDocument($source).join()
  • Restore a batch of deleted documents (since 10.10RC1)
    #set ($batchId = $deletedDocument.batchId)
    $services.refactoring.restore($batchId)
  • Permanently delete a batch of deleted documents (since 10.10RC1)
    #set ($batchId = $deletedDocument.batchId)
    $services.refactoring.permanentlyDelete($batchId)

Debugging

If some operation failed you can see what got executed by doing the following:

  • Find the id of the job by checking [Permanent directory]/jobs/status/refactoring/<operation>/
  • In a new page add the following snippet (and replace with your operation and job id):
    {{velocity}}
    #template('job_macros.vm')
    #set ($status = $services.job.getJobStatus(["refactoring", "move", "1502984592653-433"]))
    {{html}}
    #displayJobStatusLog($status, false)
    {{/html}}
    {{/velocity}}

    Example:

    debugging.png

Tags:
Created by Marius Dumitru Florea on 2015/07/16 17:28
    

Get Connected