Wave Operations

This is the second post in my series on the basics of Google Wave. This initial series of posts is provided to get a reader up to speed prior to embarking onto the later posts I am planning in regards to creating a Wave Service Provider.

Wavelets are operated on by a set of wave operations. A set of operation elements are sent WSP to WSP packaged in a delta element (more will be discussed about delta's in the Wave Message Flow post).

The operation element is a container that wraps a single action. Note: I am specifiying attributes for the elements in ()'s after the element name. The set of actions are as follows:

• noop - do nothing
• add-participant (user-id)
• remove-participant (user-id)
• mutate-document (document-id) - apply a set of document changes to the given document

All of these are pretty straight forward except for the mutate-document element. This has one attribute the document to modify, and a list of document operations. When you start a mutate-document the cursor is positioned at the beginning of the document and all document operations are performed based on the current cursor position. To create a new document within a wavelet a new document-id is specified. To remove a document from a wavelet all content within the document is removed. The set of document operations are as follows:

General Content Editing:

• skip (size) - number of characters to move cursor forward (only forward)
• characters (characters) - insert the given characters at the cursor, moves cursor forward the length of characters
• delete-characters (size) - deletes size number of characters after the cursor, cursor stays where it is

Adding / Removing / Editing XML structure:

• element-start (name) - start an XML element of type name, has a set of child attribute elements with name and value attributes, move cursor forward one character (note: elements are counted as one character)
• element-end - this places an end to the most recently started element move cursor forward one character
• delete-element-start - deletes the start element under the cursor, cursor stays where it is
• delete-element-end - delete the end element under the cursor, cursor stays where it is
• set-attributes - sets attributes on the element under the the cursor, has a set of child attribute elements with name and value attributes (first clears the current attributes), cursor doesn't move
• update-attributes - same as set attributes but doesn't clear the current attributes, cursor doesn't move

Special Annotations:

• start-annotation (key, value) - annotations are used to mark up sections of the document independantly to the elements, if the value is not set both the start and the end annotations with this key are deleted
• end-annotation (key) - marks the end of the annotation

Splitting XML Elements:

• anti-element-start - adds end element to closest element to the left, this is used to split the element that the cursor is within, moves the cursor forward one character
• anti-element-end - matches the previous anti-element-start, creates element matching element ended by antielementstart, has a set of child attribute elements with name and value attributes, moves cursor forward one character

i.e. to change "<p>test this content</p>" into "<p>test</p> this <p>content</p>" there would be an anti-element-start after the "test" and an anti-element-end before the "content".

Joining XML Elements:

• delete-anti-element-start - deletes the end element under the cursor, cursor stays where it is
• delete-anti-element-end - deletes an start element under the cursor, cursor stays where it is

i.e. to change "<p>test</p> this <p>content</p>" into "<p>test this content</p>" there would be an delete-anti-element-start after the "test" and an delete-anti-element-end before the "content".

Each of the element related modifications requires that the matching end operation is also performed to keep the document well formed. If this isn't the case the mutate-document should be rejected.

Only a small set of operations in total, but enough to get the job done.

Update: I have updated this based on the most recent version of the specification as at June 8, 2009.