Locking system

A resource can be locked or not. If the resource is locked, it means that this resource contains at least one lock. A lock is defined by :

• A owner of the lock (the uid of the authenticated user) [string]
• A uuid (a unique server-wide id) [string]
• A owner information (an information provided when creating the lock) [optional] [string or XML]
• An expiration date [number]
• A lock kind (which is a wrapper) [LockKind]
  • A scope [LockScope]
  • A type [LockType]

The type of the lock provides information about what is prohibited. At the moment, the server implements (and the RFC4918 specify) only one type of lock : Write. The Write type prohibits any write operation while unlocked resources can be written in parallel with possible conflicts.

The scope of the lock tells if a lock can be shared or if it is exclusive. A shared lock resource means that the resource can be locked by many users. This involves to trust the others users to not create conflicts. In opposite, an exclusive lock will prohibit any user to take a lock, making the owner of the lock the unique authorized user until the lock is removed by its timeout or by the owner.

It is a good practice to lock (exclusive scope) before writing content to a resource and unlock at the reception of the response.

As said the RFC4918, you must not rely on the lock system to provide privilege to a resource. Instead, use the user management system.

Sometimes, it is important to be able to refresh a lock. For instance, a lock can be made before writing to a resource, but the content will takes hours to be completely sent ; so, at regular intervals, the client can send a refresh lock request to keep the lock alive.

If a parent resource is locked, the lock will apply to all of its children. At the moment, there is no way to lock just the resource and not the children too (making it not completely compliant with the RFC4918).

Using the method PROPFIND on a resource will provide the list of all alive locks affecting it.

If you want more information about the locking system, you can look at the RFC4918.