Web Distributed Authoring and Versioning (WebDAV) Locking Protocol

The terminology used here follows and extends that in the WebDAV Distributed Authoring Protocol specification [RFC2518].¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].¶

Since this document describes a set of extensions to the WebDAV Distributed Authoring Protocol [RFC2518], itself an extension to the HTTP/1.1 protocol, the augmented BNF used here to describe protocol elements is exactly the same as described in Section 2.1 of [RFC2616]. Since this augmented BNF uses the basic production rules provided in Section 2.2 of [RFC2616], these rules apply to this document as well.¶

This document uses XML DTD fragments ([XML]) as a purely notational convention. WebDAV request and response bodies cannot be validated due to the specific extensibility rules defined in section 23 of [RFC2518] and due to the fact that all XML elements defined by this specification use the XML namespace name "DAV:". In particular: ¶

• Element names use the "DAV:" namespace.
• Element ordering is irrelevant.
• Extension elements/attributes (elements/attributes not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise.

A "precondition" of a method describes the state on the server that must be true for that method to be performed. A "postcondition" of a method describes the state on the server that must be true after that method has completed. If a method precondition or postcondition for a request is not satisfied and unless a more specific HTTP status code applies, the response status of the request MUST be either 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request.¶

In order to allow better client handling of error responses, a distinct XML element type is associated with each method precondition and postcondition of a request. When a particular precondition is not satisfied or a particular postcondition cannot be achieved, the appropriate XML element MUST be returned as the child of a top-level DAV:error element in the response body, unless otherwise negotiated by the request. In a 207 Multi-Status response, the DAV:error element would appear in the appropriate DAV:responsedescription element.¶

The most basic form of lock is an exclusive lock. This is a lock where the access right in question is only granted to a single principal. The need for this arbitration results from a desire to avoid having to merge results.¶

However, there are times when the goal of a lock is not to exclude others from exercising an access right but rather to provide a mechanism for principals to indicate that they intend to exercise their access rights. Shared locks are provided for this case. A shared lock allows multiple principals to receive a lock. Hence any principal with appropriate access can get the lock.¶

With shared locks there are two trust sets that affect a resource. The first trust set is created by access permissions. Principals who are trusted, for example, may have permission to write to the resource. Among those who have access permission to write to the resource, the set of principals who have taken out a shared lock also must trust each other, creating a (typically) smaller trust set within the access permission write set.¶

Starting with every possible principal on the Internet, in most situations the vast majority of these principals will not have write access to a given resource. Of the small number who do have write access, some principals may decide to guarantee their edits are free from overwrite conflicts by using exclusive write locks. Others may decide they trust their collaborators will not overwrite their work (the potential set of collaborators being the set of principals who have write permission) and use a shared lock, which informs their collaborators that a principal may be working on the resource.¶

This specification does not need to provide all of the communications paths necessary for principals to coordinate their activities. When using shared locks, principals may use any out of band communication channel to coordinate their work (e.g., face-to-face interaction, written notes, post-it notes on the screen, telephone conversation, Email, etc.) The intent of a shared lock is to let collaborators know who else may be working on a resource.¶

Shared locks are included because experience from web distributed authoring systems has indicated that exclusive locks are often too rigid. An exclusive lock is used to enforce a particular editing process: take out an exclusive lock, read the resource, perform edits, write the resource, release the lock. This editing process has the problem that locks are not always properly released, for example when a program crashes, or when a lock owner leaves without unlocking a resource. While both timeouts and administrative action can be used to remove an offending lock, neither mechanism may be available when needed; the timeout may be long or the administrator may not be available. With a shared lock, another user can at least take out another shared lock and start modifying the resource.¶

A WebDAV compliant server is not required to support locking in any form. If the server does support locking it may choose to support any combination of exclusive and shared locks for any access types.¶

The reason for this flexibility is that locking policy strikes to the very heart of the resource management and versioning systems employed by various storage repositories. These repositories require control over what sort of locking will be made available. For example, some repositories only support shared write locks while others only provide support for exclusive write locks while yet others use no locking at all. As each system is sufficiently different to merit exclusion of certain locking features, this specification leaves locking as the sole axis of negotiation within WebDAV.¶

A lock token is a type of state token, represented as a URI, which identifies a particular lock (see [RFC2518], section 9.4, for a definition of state tokens). A lock token is returned by every successful LOCK operation in the Lock-Token response header. The lock token also appears in the value of the DAV:lockdiscovery property, the value of which is returned in the body of the response to a successful LOCK operation (note that this property also includes the tokens of other current locks on the resource).¶

Lock token URIs MUST be unique across all resources for all time. This uniqueness constraint allows lock tokens to be submitted across resources and servers without fear of confusion.¶

This specification provides a lock token URI scheme called "opaquelocktoken" that meets the uniqueness requirements. However servers are free to ↑ I ↓returnuse any URI scheme so long as it meets the uniqueness requirements↑ I ↓(for example, the "urn:uuid" URN namespace defined in [RFC4122]). Note that only URI schemes registered by the IETF can ensure uniqueness.¶

Submitting a lock token provides no special access rights. Anyone can find out anyone else's lock token by performing lock discovery. Locks MUST be enforced based upon whatever authentication mechanism is used by the server, not based on the secrecy of the token values.¶

Since server lock support is optional, a client trying to lock a resource on a server can either try the lock and hope for the best, or perform some form of discovery to determine what lock capabilities the server supports. This is known as lock capability discovery. Lock capability discovery differs from discovery of supported access control types, since there may be access control types without corresponding lock types. A client can determine what lock types the server supports by retrieving the DAV:supportedlock property defined in Section 4.3.¶

A lock is identified by a URI (the lock token URI) but in general, it does not have a HTTP URL, and thus can not be directly manipulated using HTTP methods. Instead, this specification defines the new methods LOCK (creating and refreshing locks, see Section 5) and UNLOCK (removing locks, see Section 6) that act indirectly on locks.¶

A lock has state that can be indirectly observed by using the DAV:lockdiscovery property defined in Section 4.2. At a minimum, the state of a lock consists of the items defined in the sections below. After lock creation, all parts of the state with the exception of the timeout value are immutable.¶

If another principal locks a resource that a principal wishes to access, it is useful for the second principal to be able to find out who the first principal is. For this purpose the DAV:lockdiscovery property is provided. This property lists all outstanding locks, describes their type, and where available, provides their lock token.¶

• Two clients A and B are interested in editing the resource 'index.html'. Client A is an HTTP client rather than a WebDAV client, and so does not know how to perform locking.
• Client A doesn't lock the document, but does a GET and begins editing.
• Client B does LOCK, performs a GET and begins editing.
• Client B finishes editing, performs a PUT, then an UNLOCK.
• Client A performs a PUT, overwriting and losing all of B's changes.

There are several reasons why the WebDAV protocol itself cannot prevent this situation. First, it cannot force all clients to use locking because it must be compatible with HTTP clients that do not comprehend locking. Second, it cannot require servers to support locking because of the variety of repository implementations, some of which rely on reservations and merging rather than on locking. Finally, being stateless, it cannot enforce a sequence of operations like LOCK / GET / PUT / UNLOCK.¶

WebDAV servers that support locking can reduce the likelihood that clients will accidentally overwrite each other's changes by requiring clients to lock resources before modifying them. Such servers would effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying resources.¶

WebDAV clients can be good citizens by using a lock / retrieve / write /unlock sequence of operations (at least by default) whenever they interact with a WebDAV server that supports locking.¶

HTTP 1.1 clients can be good citizens, avoiding overwriting other clients' changes, by using entity tags in If-Match headers with any requests that would modify resources.¶

Information managers may attempt to prevent overwrites by implementing client-side procedures requiring locking before modifying WebDAV resources.¶

If a request would modify the content for a locked resource, a dead property of a locked resource, a live property that is defined to be lockable for a locked resource, or an internal member URI of a locked collection, the request MUST fail unless the lock-token for that lock is submitted in the request. An internal member URI of a collection is considered to be modified if it is added, removed, or identifies a different resource  I ↓. [rfc.comment.1: Copy of GULP, "Locked State". --reschke] ¶

While those without a write lock may not alter a property on a resource it is still possible for the values of live properties to change, even while locked, due to the requirements of their schemas. Only dead properties and live properties defined to respect locks are guaranteed not to change while write locked.¶

A write lock on a collection, whether created by a "Depth: 0" or "Depth: infinity" lock request, prevents the addition or removal of member URIs of the collection by non-lock owners. As a consequence, when a principal issues a PUT or POST request to create a new resource under a URI which needs to be an internal member of a write locked collection to maintain HTTP namespace consistency, or issues a DELETE to remove an internal member URI of a write locked collection, this request MUST fail if the principal does not have a write lock on the collection.¶

However, if a write lock request is issued to a collection containing member URIs identifying resources that are currently locked in a manner which conflicts with the write lock, the request MUST fail with a 423 (Locked) status code (Note that this can only occur for a request of a "Depth: infinity" write lock).¶

If a lock owner causes the URI of a resource to be added as an internal member URI of a "Depth: infinity" locked collection then the new resource MUST be automatically added to the lock. This is the only mechanism that allows a resource to be added to a write lock. Thus, for example, if the collection /a/b/ is write locked and the resource /c is moved to /a/b/c then resource /a/b/c will be added to the write lock.¶

If a user agent is not required to have knowledge about a lock when requesting an operation on a locked resource, the following scenario might occur. Program A, run by User A, takes out a write lock on a resource. Program B, also run by User A, has no knowledge of the lock taken out by Program A, yet performs a PUT to the locked resource. In this scenario, the PUT succeeds because locks are associated with a principal, not a program, and thus program B, because it is acting with principal A's credential, is allowed to perform the PUT. However, had program B known about the lock, it would not have overwritten the resource, preferring instead to present a dialog box describing the conflict to the user. Due to this scenario, a mechanism is needed to prevent different programs from accidentally ignoring locks taken out by other programs with the same authorization.¶

In order to prevent these collisions a lock token MUST be submitted in the If header for all locked resources that a method may interact with or the method MUST fail. For example, if a resource is to be moved and both the source and destination are locked then two lock tokens must be submitted, one for the source and the other for the destination.¶

Servers SHOULD restrict usage of the lock token to exactly the authenticated principal who created the lock.¶

A COPY method invocation MUST NOT duplicate any write locks active on the source. However, as previously noted, if the COPY copies the resource into a collection that is locked with "Depth: infinity", then the resource will be added to the lock.¶

A successful MOVE request on a write locked resource MUST NOT move the write lock with the resource. However, the resource is subject to being added to an existing lock at the destination, as specified in Section 3.3. For example, if the MOVE makes the resource a child of a collection that is locked with "Depth: infinity", then the resource will be added to that collection's lock. Additionally, if a resource locked with "Depth: infinity" is moved to a destination that is within the scope of the same lock (e.g., within the namespace tree covered by the lock), the moved resource will again be a added to the lock. In both these examples, as specified in Section 3.4, an If header must be submitted containing a lock token for both the source and destination.¶

The DAV:lockdiscovery property returns a listing of who has a lock, what type of lock he has, the timeout type, the time remaining on the timeout, the associated lock token and the root of the lock. The server is free to withhold any or all of this information if the requesting principal does not have sufficient access rights to see the requested data.¶

depth: the value of the Depth header (see Section 2.5.4; takes the values "0" or "infinity").

   <!ELEMENT depth (#PCDATA) >

owner: provides information about the principal taking out a lock (see Section 2.5.5).

   <!ELEMENT owner ANY>

timeout: the time remaining until timeout of a lock (see Section 2.5.7).

   <!ELEMENT timeout (#PCDATA) >

locktoken: the lock token associated with a lock; the href element contains the lock token.

   <!ELEMENT locktoken (href) >
   <!-- href: defined in [RFC2518], Section 12.3 -->

lockroot: the URL that was specified as Request-URI in the LOCK creation request; the href element contains the URL↑ I ↓(see Section 2.5.3).

   <!ELEMENT lockroot (href) >
   <!-- href: defined in [RFC2518], Section 12.3 -->

The DAV:supportedlock property of a resource returns a listing of the combinations of scope and access types which may be specified in a lock request on the resource. Note that the actual contents are themselves controlled by access controls so a server is not required to provide information the client is not authorized to see.¶

A LOCK method invocation with non-empty request body creates the lock specified by the lockinfo XML element on the resource identified by the Request-URI.¶

If the Request-URI identifies a null resource, the invocation MUST create a new resource with empty content.¶

A LOCK request with no request body is a "LOCK refresh" request. It's purpose is to restart all timers associated with a lock.¶

The request MUST include a "Lock-Token" header (see Section 9.1) that identifies the lock to be removed.¶

>>Request

   UNLOCK /workspace/webdav/info.doc HTTP/1.1
   Host: example.com
   Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
   Authorization: Digest username="ejw",
      realm="ejw@example.com", nonce="...",
      uri="/workspace/webdav/proposal.doc",
      response="...", opaque="..."

>>Response

   HTTP/1.1 204 No Content

In this example, the lock identified by the lock token "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully removed from the resource http://example.com/workspace/webdav/info.doc. If this lock included more than just one resource, the lock is removed from all resources included in the lock. Note that clients MUST interpret any of the success status codes defined in [RFC2616], section 10.2 as success codes. 204 (No Content) was used here merely for consistency with the example in [RFC2518], section 8.11.1). The remainder of the document discusses Capability Discovery, Security Considerations, Internationalization Considerations and IANA Considerations. Appendices discuss changes from RFC2518 (Appendix B) and the "opaquelocktoken" URI scheme (Appendix D).¶

The 423 (Locked) status code means the source or destination resource of a method is locked.¶

This section defines additional condition names (see Section 1.2) that apply to all methods.¶

This section defines names (see Section 1.2) for new conditions introduced by locking semantics. Otherwise noted otherwise, they apply to all methods.¶

The Lock-Token request header is used with the UNLOCK method to identify the lock to be removed. The lock token in the Lock-Token request header MUST identify a lock that contains the resource identified by Request-URI as a member.¶

The Lock-Token response header is used with the LOCK method to indicate the lock token created as a result of a successful LOCK request to create a new lock.¶

Note that the "Lock-Token" request header does not contribute to the precondition checks defined for the HTTP status 412 (see [RFC2616], section 10.4.13).¶

   TimeOut       = "Timeout" ":" 1#TimeType
   TimeType      = (TimeTypeSec | "Infinite" | Other)
   TypeTypeSec   = "Second-" 1*digit
   Other         = "Extend" field-value
   ; field-value: see [RFC2616], Section 4.2

(Linear white space (LWS) MUST NOT be used inside "TimeTypeSec".)

Clients MUST NOT submit a Timeout request header with any method other than a LOCK method.¶

A Timeout request header MUST contain at least one TimeType and may contain multiple TimeType entries. The purpose of listing multiple TimeType entries is to indicate multiple different values and value types that are acceptable to the client. The client lists the TimeType entries in order of preference.¶

Timeout response values MUST use a Second value, Infinite, or a TimeType the client has indicated familiarity with. The server may assume a client is familiar with any TimeType submitted in a Timeout header.¶

The "Second" TimeType specifies the number of seconds that will elapse between granting of the lock at the server, and the automatic removal of the lock. The timeout value for TimeType "Second" MUST NOT be greater than 2^32-1.¶

If the server supports locking, it MUST return both the compliance class names "2" and "locking" as fields in the "DAV" response header (see [RFC2518], section 9.1) from an OPTIONS request on any resource implemented by that server. A value of "2" or "locking" in the "DAV" response header MUST indicate that the server meets all class "1" requirements defined in [RFC2518] and supports all MUST level requirements and REQUIRED features specified in this document, including: ¶

• LOCK and UNLOCK methods,
• DAV:lockdiscovery and DAV:supportedlock properties,
• "Time-Out" request header, "Lock-Token" request and response header.

Note that for servers implementing this specification, the compliance classes "2" and "locking" are synonymous. However, new clients can take advantage of the new "locking" compliance class to detect server support for changes introduced by this specification (see Appendix B).¶

When submitting a lock request a user agent may also submit an owner XML field giving contact information for the person taking out the lock (for those cases where a person, rather than a robot, is taking out the lock). This contact information is stored in a DAV:lockdiscovery property on the resource, and can be used by other collaborators to begin negotiation over access to the resource. However, in many cases this contact information can be very private, and should not be widely disseminated. Servers SHOULD limit read access to the DAV:lockdiscovery property as appropriate. Furthermore, user agents SHOULD provide control over whether contact information is sent at all, and if contact information is sent, control over exactly what information is sent.¶

15.1. Normative References

[RFC2119]

Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.

[RFC2518]

Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, “HTTP Extensions for Distributed Authoring -- WEBDAV”, RFC 2518, February 1999.

[RFC2616]

Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1”, RFC 2616, June 1999.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax”, STD 66, RFC 3986, January 2005.

↑ I ↓ 

[draft-mealling-uuid-urn]

Leach, P., Mealling, M., and R. Salz, “A UUID URN Namespace”, Internet-Draft draft-mealling-uuid-urn-05 (work in progress), January 2005, <http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-05.txt>.

↑ I ↓ 

[RFC4122]

Leach, P., Mealling, M., and R. Salz, “A UUID URN Namespace”, RFC 4122, July 2005.

[XML]

Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, “Extensible Markup Language (XML) 1.0 (Third Edition)”, W3C REC-xml-20040204, February 2004, <http://www.w3.org/TR/2004/REC-xml-20040204>.

15.2. Informative References

[RFC3744]

Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, “Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol”, RFC 3744, May 2004.

A lock either directly or indirectly locks a resource.  I ↓(See Section 2.5.4) ¶

A LOCK request with a non-empty body creates a new lock, and the resource identified by the Request-URI is directly locked by that lock. The "lock-root" of the new lock is the Request-URI. If at the time of the request, the Request-URI is not mapped to a resource, a new resource with empty content MUST be created by the request. ↑ I ↓(See Section 5.1) ¶

If a collection is directly locked by a depth:infinity lock, all members of that collection (other than the collection itself) are indirectly locked by that lock. In particular, if an internal member resource is added to a collection that is locked by a depth:infinity lock, and if the resource is not locked by that lock, then the resource becomes indirectly locked by that lock. Conversely, if a resource is indirectly locked with a depth:infinity lock, and if the result of deleting an internal member URI is that the resource is no longer a member of the collection that is directly locked by that lock, then the resource is no longer locked by that lock. ↑ I ↓(See 2.5.4 and 3.5). ¶

An UNLOCK request deletes the lock with the specified lock token. The Request-URI of the request MUST identify a resource that is either directly or indirectly locked by that lock. After a lock is deleted, no resource is locked by that lock. ↑ I ↓(See Section 6) ¶

A lock token is "submitted" in a request when it appears in an "If" request header. ↑ I ↓(See Section 3.4) ¶

If a request would modify the content for a locked resource, a dead property of a locked resource, a live property that is defined to be lockable for a locked resource, or an internal member URI of a locked collection, the request MUST fail unless the lock-token for that lock is submitted in the request. An internal member URI of a collection is considered to be modified if it is added, removed, or identifies a different resource. ↑ I ↓(See 3.1 and 8.2.2). ¶

If a request causes a directly locked resource to no longer be mapped to the lock-root of that lock, then the request MUST fail unless the lock-token for that lock is submitted in the request. If the request succeeds, then that lock MUST have been deleted by that request. ↑ I ↓(See 3.5, 8.2.2 and 8.3.1) ¶

If a request would cause a resource to be locked by two different exclusive locks, the request MUST fail. ↑ I (See Section 2.1) ¶

Add and resolve issue "rfc2606-compliance". Resolve issues "extract-locking", "updated-rfc2068", "022_COPY_OVERWRITE_LOCK_NULL", "025_LOCK_REFRESH_BY_METHODS", "037_DEEP_LOCK_ERROR_STATUS", "039_MISSING_LOCK_TOKEN", "040_LOCK_ISSUES_01", "040_LOCK_ISSUES_02", "040_LOCK_ISSUES_05", "043_NULL_LOCK_SLASH_URL", "065_UNLOCK_WHAT_URL", "077_LOCK_NULL_STATUS_CREATION", "080_DEFER_LOCK_NULL_RESOURCES_IN_SPEC", "089_FINDING_THE_ROOT_OF_A_DEPTH_LOCK", "101_LOCKDISCOVERY_FORMAT_FOR_MULTIPLE_SHARED_LOCKS", "109_HOW_TO_FIND_THE_ROOT_OF_A_LOCK" and "111_MULTIPLE_TOKENS_PER_LOCK". Add issue "import-gulp". Start work on moving text from RFC2518 excerpts into new sections. Define new compliance class "locking" (similar to "bis" in RFC2518bis, but only relevant to locking). Reformatted "GULP" into separate subsections for easier reference.¶

Update "008_URI_URL", "040_LOCK_ISSUES_06", "063_LOCKS_SHOULD_THEY_USE_AN_IF_HEADER_TO_VERIFY", "067_UNLOCK_NEEDS_IF_HEADER", "068_UNLOCK_WITHOUT_GOOD_TOKEN". Re-opened "065_UNLOCK_WHAT_URL". Close "070_LOCK_RENEWAL_SHOULD_NOT_USE_IF_HEADER". Rewrite UNLOCK and LOCK refresh method descriptions. Fix page title (TXT version). Close "052_LOCK_BODY_SHOULD_BE_MUST", "054_IF_AND_AUTH", "060_LOCK_REFRESH_BODY" and "079_UNLOCK_BY_NON_LOCK_OWNER". Add and resolve "8.10.1_lockdiscovery_on_failure". Started attempt to clarify status code.¶

Resolve issues "040_LOCK_ISSUES_03", "040_LOCK_ISSUES_04", "040_LOCK_ISSUES_08" "053_LOCK_INHERITANCE", "057_LOCK_SEMANTICS", "067_UNLOCK_NEEDS_IF_HEADER" and "068_UNLOCK_WITHOUT_GOOD_TOKEN". Resolve issue "065_UNLOCK_WHAT_URL"; update to new GULP version (5.7). Add and resolve new issue "7.5_DELETE_vs_URIs". Start work on "additional marshalling" and "introduction". Update issues "044_REPORT_OTHER_RESOURCE_LOCKED" and "066_MUST_AN_IF_HEADER_CHECK_THE_ROOT_OF_URL".¶

Close issues "import-rfc3253-stuff", "008_URI_URL", "015_MOVE_SECTION_6.4.1_TO_APPX", "044_REPORT_OTHER_RESOURCE_LOCKED", "056_DEPTH_LOCK_AND_IF" and "072_LOCK_URL_WITH_NO_PARENT_COLLECTION". Reformat condition name descriptions. Add mention of condition failure signalling to "Changes" appendix. Start edit of header descriptions (Depth, Timeout) and LOCK creation description. Open and close issue "3.2_lockdiscovery_depth". Start work on intro.¶

Add description of the lock as a resource and it's state (merging in Timeout semantics from old headers section). Close issues "040_LOCK_ISSUES_06", "063_LOCKS_SHOULD_THEY_USE_AN_IF_HEADER_TO_VERIFY" and "088_DAVOWNER_FIELD_IS_CLIENT_CONTROLED". Move edited version of "Write Lock" chapter.¶

Add and close issues "rfc2396bis" and "5.2.1-depth_header_vs_lock_refresh". Fixed DAV:lockdiscovery example.¶

Add and resolve issues "uri_draft_ref", "abnf", "D_delegate_UUID_definition" and "lock_state_auth_principal".¶