3.1.4.4 SchemaLock Subrequest

  • Article

This operation is used to request a shared lock on a file or shared lock operations on a coauthorable file from the protocol server. The schema lock subrequest is conceptually a subset of the coauthoring subrequest and differs from the coauthoring subrequest by not keeping track of the clients currently in the coauthoring session that are sharing the lock on the file.

The term schema lock means that all clients with the same schema lock identifier share the lock and that clients with different schema lock identifiers are required to wait until the shared lock is released by all the clients having the same schema lock identifier. Depending on the SchemaLockRequestType attribute value, the protocol server interprets the request as one of the following types of lock operations:

  • Get lock.

  • Release lock.

  • Refresh lock.

  • Convert to exclusive lock.

  • Check lock availability.

The SchemaLockRequestType attribute is defined in section 2.3.2.4. The SubRequestData element for the schema lock subrequest is of type SchemaLockSubRequestDataType and is defined in section 2.3.1.13.

The protocol client sends a schema lock SubRequest message, which is of type SchemaLockSubRequestType as specified in section 2.3.1.14. The protocol server responds with a schema lock SubResponse message, which is of type SchemaLockSubResponseType as specified in section 2.3.1.16. This is done as follows:

  • The protocol client prepares a request containing a URL for the file, a unique Request token, and one or more SubRequest elements, as defined in section 2.2.3.2 and section 2.2.3.8. The SubRequest element is of type "SchemaLock" and the SubRequestData element contains attributes that are input parameters used by the protocol server when processing the schema lock subrequest. The SubRequestData element is of type, SchemaLockSubRequestDataType and is defined in section 2.3.1.13.

  • The protocol server receives the request and parses the logic, and depending on the type of schema lock subrequest, the protocol sever process the request as specified in section 3.1.4.4.1, 3.1.4.4.2, 3.1.4.4.3, 3.1.4.4.4, or 3.1.4.4.5. The protocol server uses the ClientID attribute sent in a schema lock subrequest to uniquely identify each client and keep track of each client’s timeout on the shared lock for the file. The protocol server also uses the ClientID sent in the schema lock subrequest to decide when to release the shared lock on the file. The protocol server does the following to decide when to release the shared lock on the file:

    • If the timeout expires for a client and no refresh on the timeout has been received, the protocol server MUST release that client’s lock on the shared file. When the timeout for all the clients holding a shared lock on the file expire, the shared lock on the file is released by the protocol server.

  • The Response element is as defined in section 2.2.3.5, and the SubResponse element is as defined in section 2.2.3.10. The SchemaLockSubResponseDataType defines the type of the SubResponseData element inside the schema lock SubResponse element. The SchemaLockSubResponseDataType is defined in section 2.3.1.15.

  • If the schema lock subrequest is of type "Get lock" or "Refresh lock", the protocol server MUST return the lock type granted to the client as part of the response message to the client—if the ErrorCode attribute that is part of the SubResponse element is set to a value of "Success". The lock type is sent as the LockType attribute in the schema lock SubResponseData element. The SubResponseData element returned for a schema lock subrequest is of type SchemaLockSubResponseDataType and is defined in section 2.3.1.15. The LockType attribute is specified in section 2.3.1.15. The LockType attribute values are specified in section 2.2.5.9.

  • The protocol server returns results based on the following conditions:

    • Depending on the type of error, the ErrorCode value is returned as an attribute of the SubResponse element. The ErrorCode attribute that is part of the SubResponse element is updated with a specific error code as specified in section 2.2.5.4.

    • If the protocol server was unable to find the URL for the file specified in the Url attribute, the protocol server reports a failure by returning an error code value set to "FileNotExistsOrCannotBeCreated" in the ErrorCode attribute sent back in the SubResponse element.

    • The protocol server returns an error code value set to "CoauthRefblobConcurrencyViolation" when there is a concurrency violation and the schema lock subrequest is one of the following types:

      • Get lock

      • Release lock

      • Refresh lock

      • Convert to an exclusive lock

    • A concurrency violation happens when a current client’s request to save the file coauthoring tracker fails because another client’s request to edit and save the file coauthoring tracker is in progress on the server before the save is done by the current client. "CoauthRefblobConcurrencyViolation" is specified in section 2.2.5.8. The file coauthoring tracker is defined in section 3.1.1.

    • The protocol server returns an error code value set to "RequestNotSupported" if the server does not support this request type.

    • An ErrorCode value of "Success" indicates success in processing the schema lock request.