Reference

When a user starts editing a Page that is already locked by another user, XWiki asks them to confirm that they want to take over the lock. That confirmation is not useful when taking over the lock is harmless, for instance when both users are about to edit the Page together in a realtime collaboration session. XWiki 18.8.0+ An extension can waive the confirmation by providing an org.xwiki.doc.lock.UnlockRule component.

The Unlock Rule Role

package org.xwiki.doc.lock;

@Unstable
@Role
public interface UnlockRule
{
    /**
     * @param context describes the document whose lock the current user is about to take over, and how
     *            that document is going to be edited
     * @return {@code true} if the lock can be taken over without asking the user to confirm,
     *         {@code false} otherwise
     */
    boolean canUnlock(LockContext context);
}

A rule that doesn't apply to the described situation returns false.

The Lock Context

Each rule is evaluated against an org.xwiki.doc.lock.LockContext, which describes the document whose lock is about to be taken over and the way it is going to be edited:

The supported edit modes are:

How the Rules Are Evaluated

• The rules are evaluated only when the document is locked by another user. Nothing is evaluated when the document is not locked, or when the lock is held by the current user.
• The rules are looked up from the context component manager on each check, so a rule provided by a wiki component, or by an extension installed later, is taken into account.
• The rules are evaluated until one of them returns true, in which case the lock is taken over without confirmation. Each rule is expected to decide on its own whether it applies, without relying on the order in which the rules are evaluated.
• If the rules cannot be looked up, a warning is logged and the confirmation is shown.

Example

@Component
@Singleton
@Named("myEditor")
public class MyEditorUnlockRule implements UnlockRule
{
    @Inject
    private MySessionManager sessionManager;

    @Override
    public boolean canUnlock(LockContext context)
    {
        EditMode editMode = context.getEditMode();
        return (editMode == EditMode.WYSIWYG || editMode == EditMode.INPLACE)
            && "myEditor".equals(context.getContentEditor())
            && this.sessionManager.hasSession(context.getDocumentReferenceWithLocale());
    }
}

The Rules Provided by XWiki

Each of these rules comes with the extension that provides the corresponding editor, so it applies only when that extension is installed.

Note that a rule looks at the collaboration session that is in progress for the edited document, not at the user who holds the lock: the confirmation is waived as soon as there is a session to join.

Neither rule waives the confirmation for the INLINE edit mode, even though both editors can be used there (e.g. for TextArea properties), because only the content edited with those editors is synchronized in realtime: the values set on the other form fields would overwrite each other.

Replacing the Previous Mechanism

Before XWiki 18.8.0RC1 the only way to waive the confirmation was to extend the documentLock edit confirmation checker (org.xwiki.model.validation.edit.XWikiDocumentLockEditConfirmationChecker) and to register the subclass under the same component hint, with a priority that made it take precedence. Only one extension at a time could do this, and the subclass depended on a platform class that is not meant to be extended. Provide an UnlockRule instead.

Related

• BlockNote Editor.
• Page Locking.