2.3.1.13 SchemaLockSubRequestDataType

  • Article

The SchemaLockSubRequestDataType complex type contains information about data or input parameters used in processing a schema lock subrequest. The SchemaLockID attribute and the SchemaLockRequestType attribute specified in the SchemaLockSubRequestDataOptionalAttributes attribute group MUST both be specified for a schema lock subrequest. The SchemaLockID attribute and the SchemaLockRequestType attribute are specified as part of the SubRequestData element associated with a schema lock SubRequest element. SchemaLockSubRequestDataOptionalAttributes is defined in section 2.3.3.5. If the SchemaLockRequestType attribute is not provided, an error code SHOULD<33> be returned. If other attributes are not provided, an "InvalidArgument" error code MUST be returned as part of the SubResponseData element associated with the schema lock subresponse.

 <xs:complexType name="SchemaLockSubRequestDataType">
     <xs:attributeGroup ref="tns:SchemaLockSubRequestDataOptionalAttributes"/>
     <xs:attribute name="ClientID" type="xs:string" use="optional"/>
     <xs:attribute name="AllowFallbackToExclusive" type="xs:boolean" use="optional" />
     <xs:attribute name="ReleaseLockOnConversionToExclusiveFailure" type="xs:boolean" use="optional"/>
     <xs:attribute name="SchemaLockID" type="xs:string" use="required" />
     <xs:attribute name="Timeout" type="xs:integer" use="optional" />
     <xs:attribute name="ExclusiveLockID" type="xs:string" use="optional"/>
 </xs:complexType>

SchemaLockSubRequestDataOptionalAttributes: An attribute group that specifies the set of attributes that are provided only for a SubRequestData element whose parent SubRequest element’s Type attribute is set to "SchemaLock". SchemaLockSubRequestDataOptionalAttributes is defined in section 2.3.3.5.

ClientID: A string that serves to uniquely identify each client that has access to a shared lock on a coauthorable file. ClientID MUST be specified on all types of schema lock subrequests. The different types of schema lock subrequest are defined in section 2.3.3.5.

AllowFallbackToExclusive: A Boolean value that specifies to a protocol server whether a schema lock subrequest is allowed to fall back to an exclusive lock subrequest provided that shared locking on the file is not supported. When shared locking on the file is not supported:

  • An AllowFallbackToExclusive attribute value set to true indicates that a schema lock subrequest is allowed to fall back to an exclusive lock subrequest.

  • An AllowFallbackToExclusive attribute value set to false indicates that a schema lock subrequest is not allowed to fall back to an exclusive lock subrequest.

The AllowFallbackToExclusive attribute is specified as part of a schema lock subrequest of type "Get Lock". The types of schema lock subrequest are defined in section 2.3.3.5.

ReleaseLockOnConversionToExclusiveFailure: A Boolean value that specifies to the protocol server whether the server is allowed to remove the ClientID entry associated with the current client in the File coauthoring tracker, provided that all of the following conditions are true:

  • The type of the schema lock subrequest is "Convert to an Exclusive Lock".

  • The conversion to an exclusive lock failed.

When all the preceding conditions are true, the following apply:

  • A ReleaseLockOnConversionToExclusiveFailure attribute set to a value of true indicates that the protocol server is allowed to remove the ClientID entry associated with the current client in the File coauthoring tracker.

  • A ReleaseLockOnConversionToExclusiveFailure attribute set to a value of false indicates that the protocol server is not allowed to remove the ClientID entry associated with the current client in the File coauthoring tracker.

The ReleaseLockOnConversionToExclusiveFailure attribute MUST be sent only when the schema lock subrequest type is set to "Convert to exclusive lock". The types of schema lock subrequests are defined in section 2.3.3.5. The File coauthoring tracker is defined in section 3.1.1.

SchemaLockID: A string that is globally unique and known among all protocol clients that share the same protocol version. The schema lock identifier is used by the protocol server to block other clients that have different schema identifiers. After a protocol client is able to get a shared lock for a file with a specific schema lock identifier, the server MUST allow only other protocol clients that specify the same schema lock identifier to share the file lock. The protocol server ensures that at any instant in time, only clients having the same schema lock identifier can lock the file. After all the protocol clients have released their lock for that file, the protocol server MUST allow a protocol client with a different schema lock identifier to get a shared lock for that file. The SchemaLockID attribute MUST be sent on all types of schema lock subrequests. The string "29358EC1-E813-4793-8E70-ED0344E7B73C" has been reserved for use for this attribute.<34>

Timeout: An integer that specifies the time, in seconds, after which the shared lock for that particular file will expire for that specific protocol client. The Timeout attribute MUST be set to a value ranging from 3,600 to 120,000. When the Timeout is set to a value ranging from 60 to 3600, the server also returns success but sets the Timeout to an implementation-specific default value. When more than one client is editing the file, the protocol server MUST maintain a separate timeout value for each client. The client’s timeout on a shared lock for a file is refreshed by sending a schema lock subrequest of type "Refresh lock". The Timeout attribute MUST be specified in all of the following types of schema lock subrequests:

  • Get lock

  • Refresh lock

  • Convert to exclusive lock

The types of schema lock subrequests are defined in section 2.3.3.5.

ExclusiveLockID: A string that serves as a unique identifier for the exclusive lock on the file when a schema lock subrequest of type "Convert to exclusive lock" is requested. ExclusiveLockID MUST be specified when the type of the schema lock subrequest is "Convert to exclusive lock" or "Get lock" and the AllowFallbackToExclusive attribute is set to true.