cogAPI to queue asynchronous tasks dedicated to the analysis of wiki pages.
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

Since 14.1

Installable with the Extension Manager

Description

Currently, this module provides only operations to queue asynchronous tasks dedicated to the analysis of wiki pages but in the future, it's meant to be completed with other APIs.

Asynchronous Document Static Analysis

Asynchronous analysis of document are possible with the TaskManager component. The queued tasks are persisted. In other word, they are not lost when the server is stopped, and will be queued again when the server is restarted.

TaskManager Roles

@Role
@Unstable
public interface TaskConsumer
{
   /**
     * Consume a task.
     *
     * @param documentReference of the document to analyze
     * @param version the version of the document to analyze
     * @throws IndexException in case of error during the execution of the task
     */

   void consume(DocumentReference documentReference, String version) throws IndexException;
}
@Role
@Unstable
public interface TaskManager
{
   /**
     * Add a task to the queue for a given version of a document.
     *
     * @param wikiId the wiki containing the document
     * @param docId the document id
     * @param version the document version
     * @param type the type of task to add
     * @return a completable future for this task
     */

    CompletableFuture<TaskData> addTask(String wikiId, long docId, String version, String type);

   /**
     * Add a task to the queue for the latest version of the targeted document.
     *
     * @param wikiId the wiki containing the document
     * @param docId the document id
     * @param type the type of task to add
     * @return a completable future for this task
     * @since 14.2RC1
     */

    CompletableFuture<TaskData> addTask(String wikiId, long docId, String type);

   /**
     * @return the number of tasks in the queue
     */

   long getQueueSize();

   /**
     * @param type the type of task to count
     * @return the number of  tasks of a given type in the queue
     */

   long getQueueSize(String type);

   /**
     * @param wikiId the identifier of a wiki (e.g., "xwiki")
     * @return the number of tasks grouped by task type for a given wiki
     * @since 14.2
     */

   @Unstable
   default Map<String, Long> getQueueSizePerType(String wikiId)
   {
       return Map.of();
   }
}

Adding a task to the queue

The example below is drawn for the Mentions Application implementation. The method addTask is called on TaskManager is called with the following parameters:

  • the reference of the wiki in which the document to analyze is located
  • the unique id of the document to analyze
  • the version of the document to analyze (in our example, the latest version of the document)
  • the type of the task to execute on the document (in our example, the "mention" task)
@Component
@Singleton
@Named("MentionsCreatedEventListener")
public class MentionsCreatedEventListener extends AbstractEventListener
{
   private static final List<DocumentCreatedEvent> EVENTS = singletonList(new DocumentCreatedEvent());

   @Inject
   private Logger logger;

   @Inject
   private TaskManager taskManager;

   @Inject
   private RemoteObservationManagerContext remoteObservationManagerContext;

   /**
     * Default constructor.
     */

   public MentionsCreatedEventListener()
   {
       super("MentionsCreatedEventListener", EVENTS);
   }

   @Override
   public void onEvent(Event event, Object source, Object data)
   {
       if (!(event instanceof DocumentCreatedEvent) || this.remoteObservationManagerContext.isRemoteState()) {
           return;
       }
       this.logger.debug("Event [{}] received from [{}] with data [{}].", DocumentCreatedEvent.class.getName(), source,
            data);

        XWikiDocument doc = (XWikiDocument) source;
       this.taskManager.addTask(doc.getDocumentReference().getWikiReference().getName(), doc.getId(), doc.getVersion(),
            MENTION_TASK_ID);
   }
}

Implementing a task consumer

Implementing a task consumer is done by implementing the TaskConsumer role and given a unique hint to the new component. This hint must match the type of the queued task.
For each queued task, the component corresponding to the type of the task if resolved and called.

@Component
@Singleton
@Named("mention")
public class DefaultMentionsDataConsumer implements TaskConsumer
{
   @Override
   public void consume(DocumentReference documentReference, String version) throws IndexException
   {
      // [proceed to the analysis of the document in the given version]
   }
}

JMX Monitoring

An object named org.xwiki:name=index is declared and provides two attributes:

  • getQueueSize: Returns the total number of queued tasks
  • getQueueSizePerType: Returns the total number of tasks grouped by their types

Administration

The Document Analysis administration page can be accessed in the Content section of the administration. The page displays the number of remaining tasks, grouped by task type.

document_analysis_admin.png

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-index-api 14.10):

Tags:
    

Get Connected