1. A presentation by Robin Upton (2009-10-04) ‏ Latest version at www.altruists.org/ff106 Attribution – NonCommercial - ShareAlike www.altruists.org FF106: Other Processing Directives Recommended Pre-requisite: FF6: Common Processing Directives v1.0.0 http://www.altruists.org/ff6

2. F2F servers are programmed with items, with a function attribute to indicate which service is requested. Service Request Model The f2f:escaped & f2f:sendescaped attributes modify the default processing order. * This namespace is omitted for brevity from this point on. Attributes to modify requests are called Processing Directives. This presentation details the less common ones. http://www.altruists.org/ff5

3. Interpreting a has 3 steps, apart from the transforms themselves. Processing Directive Sequence XSL transform or CORE service Raw Output Post- processed Output Pre- processed Input servicereq Raw Input servicereq Pre- processing directives: Mid- processing directives: pre-deserialize pre-validate pre-test {,-select} pre-skip pre-skip-shallow pre-update- {, -name, -namespace, -value} pre-order pre-sort {,-data-types,-keys,-order} pre-select pre-select-shallow this-return this-validate this-order this-skip this-skip-shallow this-update {, -name, -namespace, -value} this-sort {,-data-types, -keys, -order} this-select this-select-shallow this-xml-space this-escape this-escape-node this-insert {, -source{,-shallow}, -method} Raw Final Output Post- processed Final Output Post- processing directives: post-validate post-order post-skip post-skip-shallow post-update {,-name,-namespace, -value} post-sort {,-data-types, -keys, -order} post-select post-select-shallow post-xml-space post-escape-node Descendant XSL stylesheet Possible

4. Pre-Processing Directives pre-deserialize pre-validate pre-test pre-test-select pre-test-select-shallow pre-order pre-skip pre-skip-shallow pre-update- {, -name, -namespace, -value} pre-sort{,-data-types, -keys, -order} pre-select pre-select-shallow XSL transform or CORE service Pre- processed Input servicereq Raw Input servicereq Pre-processing directives: The following directives apply to the input document, before processing...

5. Mid-Processing Directives The following directives apply to the output of the first processing step... this-return this-validate this-order this-skip this-skip-shallow this-update {,-as,-namespace} this-sort {, -data-types, -keys, -order} this-select this-select-shallow this-xml-space this-escape this-escape-node this-insert {, -source{,-shallow}, -method} First XSL transform or CORE service Raw Output Post- processed Output Mid-processing directives:

6. Post-Processing Directives Post directives apply to the final output of all servicereqs created by the original request: post-validate post-order post-skip post-skip-shallow post-update {, -name, -namespace, -value} post-sort {,-data-types, -keys, -order} post-select post-select-shallow post-xml-space post-escape-node XSL transform or CORE service Raw Output Post- processed Output Mid-processing directives: Raw Final Output Post- processed Final Output Post-processing directives: Processing all offspring servicereqs. Descendant XSL stylesheets or CORE services

7. @pre-deserialize : Deserializing Text Nodes This converts serialized XML back into XML: pre ` <location>//false- flags.xml </location> @pre-deserialize= “//text()” //false-flags.xml @pre-deserialize is usually set to “//text()”, which deserializes all text nodes. It is used to allow continued processing of serialized XML content, such as that returned by calls to the f2f:core template.

8. @this-escape : Escaping with Attributes This specifies which output nodes to add escaping attributes to: mid ` //example.sreq.xml @this-escape is usually set to “/*”, to prevent any further processing. (Behaviour for “/” is currently unspecified)‏ @this-escape= “/*” Nodes which already have this attribute are unchanged.

9. @*-order : Modifying Order of Processing Directives This directive changes the order of subsequent processing directives. This directive is a superior alternative to attaching p.d.’s to a nested set of pre, mid, post <servicereq function="http://friend2friend.net/services/identity" this-select=”//f2f:item[2]” this-skip=”//f2f:item[2]” this-order=”select skip”> Reichstag Fire Sep 11th Attacks Tonkin Gulf @this-select= “//f2f:item[2]” @this-skip= “//f2f:item[2]” Sep 11th Attacks @this-skip= “//f2f:item[2]” @this-select= “//f2f:item[2]” Reichstag Fire Tonkin Gulf Without @this-order: Tonkin Gulf Sep 11th Attacks

10. @this-return : Ignoring Return of Data If =0, this directive instructs the thread not to await the servicereq’s output. @this-return= “0” is useful for operations which take a long time, such as callouts to other servers, since alternatives such as @this-select=“/..” wait for the service to complete. mid Although coded, it is not much needed yet, since F2F servers do not yet call out directly to other servers.

11. @*-sort, @*-sort-keys : Sorting This performs an XSL-style sort on the data. Both attributes are needed. pre, mid, post @*-sort* avoids need for XSL sorting, especially handy for callouts. Reichstag Fire Sep 11th Attacks Tonkin Gulf Sep 11th Attacks Tonkin Gulf Reichstag Fire @this-sort= “//f2f:list” Nodes whose children are sorted Semicolon-separated list of sort keys @this-sort-keys= “@gov ;.” @this-sort-orders= “1”Semicolon-separated list of directions @*-sort-data-types is also available to specify sort(s) on ‘number’ or ‘text’.

12. ` Example of @sort - reversing Node Order *-sort-keys may use any xpath. For example, to reverse child order: pre, mid, post //false-flags.xml Reichstag Fire Sep 11th Attacks Tonkin Gulf @this-sort= “//f2f:list” @this-sort-order=”0” @this-sort-keys=”position()” <!-- False Fag operations → Tonkin Gulf Sep 11th Attacks Reichstag Fire

13. @this-insert-* : Adding Input Branches This selects branches of input XML and appends it to the output. mid ` Reichstag Fire Sep 11th Attacks Tonkin Gulf //false-flags.xml 139 Reichstag Fire Sep 11th Attacks Tonkin Gulf @this-insert-source=“/node()” @this-skip=“/node()” is analagous to the Unix tee @this-insert-source= “//f2f:list”

14. @this-insert-* : Calculating XPaths If this evaluates to a string, it is added to the output in the same way. mid ` Reichstag Fire Sep 11th Attacks Tonkin Gulf //false-flags.xml 139 139 bytes, 3 item(s). If the Xpath result is a string, @this-insert-source or @this-insert-source- shallow are identical. If a node set, only the former keeps child nodes. @this-insert-source= “concat(‘ bytes,’, count(//f2f:item),’ item(s).’)”

15. @pre-test : Conditional Interpretation This directive is evaluated on the input document, and stops processing iff it evaluates to an empty node set, empty string, ‘false’ or ‘0’. pre‏ //false-flags.xml @pre-test= “//f2f:item” If processing is stopped, @pre-test-select or @pre-test-select-shallow is applied to the input. @pre-test is barely used as yet, and may still be subject to change, such as throwing an exception on failure. = empty node set, so no processing

16. @ * -update : Modifying node values/names This attribute is an Xpath to specify nodes to modify. pre, mid, post The changes are processed in document order, important if the nodes refer to one another. e.g, A hierarchy of folders with @names can be converted into a hierarchy of paths by using @this-update-name=”concat(../../@name, ’/’,.)”/@name Attributes The modification is described by one or more of the Xpaths below, which are evaluated with respect to the node concerned: @*-update-name @*-update-namespace @*-update-value New nameNew namespaceNew value Comments ignored New value CData ignored New value Elements New nameNew namespaceNew value P. I.’s New nameignoredNew value

17. @ * -validate : Validating Input/Output This regulates validation of particular calls. The value is either “*” (=no validation) or a URI of a service available on the soft-system. pre, mid, post ` some-string-id-for-a-change @{this,post}-validate are used internally if automatic validation is enabled. To suppress automatic input/midput/output validation of services, set the appropriate attribute= “*” in the module definition file. The only valid value of pre-validate is @pre-validate=“*”, which suppresses input validation. This may be helpful if input validation is undesirably strict (such as for the bag-read service, which requires numerical ids.

18. @ * -xml-space : Preserving Whitespace This adds an xml:space attribute to the top of the output: mid, post <!-- Transform here, which gets the width. --!> <!-- Transform here, which gets the height. --!> ` //example.xml...contents......contents......contents... @this-xml-space is for handling whitespace sensitive files (discouraged in F2F). @this-xml-space= “1”

19. //bad-servicereqs.xml //bad-servicereqs(copy).xml Safe Processing of Untrusted XML A common task is to handle any XML, without interpreting any servicereqs. adds f2f:escaped=”*” at the root element(s) so the contents will not be processed. @this-escape= “/*”

20. Safe Processing of Unknown XML - 2 The f2f:file has f2f:escaped=“*”, so now the outer request is processed: Won’t be interpreted because of the above. ::sink.xml removes the escaping item before it is processed. @pre-skip-shallow= “f2f:data/f2f:file” //bad-servicereqs(copy).xml This request writes the data from the file without having processed its contents. //bad-servicereqs(copy).xml

21. Summary Recommended Follow-up: FF7: Server Structure Their efficiency and brevity means they should be used in preference to XSLT. @ http://www.altruists.org/ff7 They modify the servicereq processing model and perform XML manipulations. Processing-directives are of 3 types, according to the order of evaluation. pre mid post