9. p:file-touch

The p:file-touch step updates the modification timestamp of a file.

<p:declare-step type="p:file-touch">
     <p:output port="result" primary="true" content-types="application/xml"/>
     <p:option name="href" required="true" as="xs:anyURI"/>        
     <p:option name="timestamp" as="xs:dateTime?"/>                
     <p:option name="fail-on-error" as="xs:boolean" select="true()"/>
</p:declare-step>

The p:file-touch step updates the modification timestamp of the file specified in the href option. If the file specified by href does not exist, an empty file will be created at the given location.

Conformant processors must support URIs whose scheme is file for the href option of p:file-touch. It is implementation-defined what other schemes are supported by p:file-touch, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. It is a dynamic error (err:XC0136) if an implementation does not support p:file-touch for a specified scheme.

If href is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-touch in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0137) if p:file-touch cannot be completed due to access restrictions in the environment in which the pipeline is run.

If the timestamp option is set, the file's timestamp is set to this value. Otherwise the file's timestamp is set to the current system's date and time.

If the operation is successful, the step returns a c:result element containing the absolute URI of the file.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error.

If an error occurs and fail-on-error is true, the following error is raised:

  • It is a dynamic error (err:XD0011) if the resource referenced by the href option does not exist and cannot be created or exists and cannot be accessed.

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.