Locking in PWS Services

Projector employs both optimistic and pessimistic locking to protect against accidental overwriting of data in a multi-user environment. In an optimistic locking scheme, a row version is returned along with data that is fetched from the database. This row version is something that is guaranteed to change if any of the data fetched along with it is updated in the database, This row version is passed back up to the server when attempting to update the data. If the specified row version does not match the row version currently stored in the database, the save operation fails. In a pessimistic locking scheme, a lock is acquired on a database entity at the time the entity details are retrieved from the database. While the lock is held, other users are prevented from making any changes. After the lock holder saves any changes, the lock is released.

PWS Web Services support locking in the following ways:

• Full support for optimistic locks. For entities that have row versions associated with them, the PWS service that retrieves the entity will include among the attributes included in the response the row version (usually called "Timestamp"). This will be in the form of a base-64 encoded binary value (a string). The corresponding service that updates the record in Projector will accept the same row version value and will fail if the database row version has changed in the meantime. There is no need for the caller to interpret the value of the timestamp, it is just important that they pass back up to the save service the same value retrieved by the retrieving service. Participation in optimistic locking is optional. The caller may choose to not pass up the row version on a save, in which case the data specified in the request will overwrite the data in the database regardless of whether it is considered "stale".
• Respect for pessimistic locks held by users of Projector applications. If an attempt is made to save changes to an entity in Projector and another user has a pessimistic lock on that entity (for example, an attempt to save changes to an engagement while a user has that engagement open in the Project Editor), the request will fail with an error indicating that the entity is locked. These services often have an optional input flag that allows the caller to steal the lock. This capability to steal locks should be used with great care, as stealing a lock can cause the original lock holder to lose all of their changes, which may involve hours of effort.

At this time, there is no support for acquiring or releasing pessimistic locks on entities in Projector through the PWS web services.