The Editor
The editor supports two handlers: editing or annotating a section.
Each operation has two parts: displaying a Form, and submitting the
Form to commit the update.
This is not considered so performance-critical ad displaying an
article, as it is likely to be a relatively infrequent (and
non-cacheable) operation. Nevertheless, it is implemented as a
module mod_annot. But mod_annot does allow itself the overhead
of parsing the document to a DOM and using XPATH expressions to
check document metadata and extract the section we are working on.
If a document is not well-formed, the parse will fail and an
HTTP Error 500 will be returned.
On all requests, mod_annot first checks that the user is authorised
for the attempted operation and that the document is not locked
against any update. If this check fails an HTTP 401 or 503 error
response will be returned as appropriate.
After these checks, one of two things happen. If the request was an
HTTP GET, it will display an editor form. If the request was a POST,
it will submit the form, making the update.
In either case, the next operation is to extract the section we are
working on from the DOM. This relies on the user submitting valid
inputs to the editor: if the inputs are not acceptable to the system
(i.e. if someone is trying to tamper with it), it will return an
HTTP 400 error. If the section cannot be extracted despite well-formed
inputs, it will return an HTTP 500 error: this could happen either
on a tamper attempt or because the section was updated between
loading a page and selecting the editor operation.
Either the annotation or edit forms are displayed within a general
page template. The annotation form displays the section with an empty
text box to enter the user's comment, while the edit form displays
the section title and the section contents (markup) in form fields
to be edited.
Submitting either of the forms causes an update to the document.
So in the case of a POST operation, the editor will take an exclusive
lock to prevent a race condition. It will also check the section
timestamp to ensure that the section is still the same as what the
user is working on, and hasn't been updated by someone else in the
meantime, returning an HTTP 409 error on failure.
An Annotation operation will insert a new annot node in the section,
escaping any markup to plain text.
An Edit operation will first validate the markup, returning an
HTTP 422 error on failure (if no section DTD is supplied, it would
merely check well-formedness). If successful, it will replace the
section title and contents in the DOM with the new values entered,
together with the timestamp and editor id.
The DOM will then be saved to a new file, and moved atomically
to the filename used to display the document. Finally, an internal
redirect returns the updated document to the user.
