#3 Live update support (might also be object history)

[Niko]

The backend should support live updating of changes of user A to user B.

Below is a proposal how to establish this.

The browser should poll in defined time intervals (e. g. 30 seconds) if an event has happened since the last time it polled. For avoiding time differences between client and server, only the server time is taken into consideration. On the first poll, the client sends an initial value. The server sends the time of the youngest update back to the client in a special field, even if it sends no events. On the next poll, the client sends this timestamp back to the server. Changes of the requesting user are not sent back to the same user. (This might be narrowed to the requesting session, leading to the requirement of storing the session id.)

As the check for updates is executed very often on the server, we require an efficient processing. Therefore, the server should have a distinct table listing all events. The table should have the columns id, event type, timestamp, affected oid, user, and event data. The timestamp should be saved in an efficient manner (native timestamp or number type, indexed) and with milliseconds or better resolution. We intentionally violate first normal normal form in event data field for ease of retrieval. The data might be saved as serialized PHP string (which might be longer than 255 chars, so MySQL text type is required).

The server can select all events to be sent to the requesting client by simply selecting all entries younger than the date the client sent. It always sends back the timestamp of the youngest entry in the table as reference timestamp for client's next request.

The following event types are proposed (these types proved to be sufficient in UWM front-end):

create: When a new object is created.
data: None.
(we might also send the new object, tbd)
(cascading creations need to be considered, tbd)

delete: When an existing object is deleted.
data: None.
(cascading deletions need to be considered, tbd)

changeLabel: When one or more display properties are changed. This event happens additionally to the changeProperty event.
data: new values for all display properties, old values for all display properties
(this proved to be useful in the front-end. As we have a limited connection to the server, this event might be skipped entirely or be integrated into the changeProperty event, e. g. by specially marking display value fields)

changeProperty: When one or more properties of an object are changed.
data: names of all changed properties, new values for all changed properties, old values for all changed properties

associate: When two objects are associated.
data: the oid of the child object. If an NM relation was involved, the child oid is the oid of the other related node, and the oid of the NM object is sent additionally. The parent object oid is stored in the oid field.

disassociate: When two object are disassociated.
data: the oid of the child object. If an NM relation was involved, the child oid is the oid of the other related node, and the oid of the NM object is sent additionally. The parent object oid is stored in the oid field.
(this needs to be consistent with disassociate action, not entirely sure about it.)

Sidenote: If only the changeProperty events were regarded, this table might be sufficient for a object history. If this was implemented, the event type column should be a a native enumeration type and might be indexed. The oid field should be indexed, as this would be a primary selection criteria for history requests. If we wanted to extend history to connections, we must make sure history entries for both ends of the connection can be found easily, either by creating two entries or by having an additional column for other end's oid (latter preferred).

If we didn't want event history, old entries might be removed from the table for performance and storage requirement reasons. Even if we wanted history, we might want to transfer older entries to a different table, for performance reasons (history requests should be much more seldom than live update requests).