Index API
 | API to queue asynchronous tasks dedicated to the analysis of wiki pages. |
| Type | JAR |
| Category | API |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | Since 14.1 |
Table of contents
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
@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;
}
@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)
@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.
@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.
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 16.3.1):
- org.xwiki.commons:xwiki-commons-component-api 16.3.1
- org.xwiki.platform:xwiki-platform-wiki-api 16.3.1
- org.xwiki.commons:xwiki-commons-stability 16.3.1
