a presentation by robin upton (2009-10-04) latest version at attribution – noncommercial -...

A presentation by Robin Upton (2009-10-04)Latest version at www.altruists.org/ff106

Attribution – NonCommercial - ShareAlikewww.altruists.org

FF106: Other Processing Directives

Recommended Pre-requisite: FF6: Common Processing Directives

v1.0.0

http://www.altruists.org/ff6


http://www.altruists.org/

F2F servers are programmed with <f2f*:servicereq> items,with a function attribute to indicate which service is requested.

Service Request Model

<servicereq function="http://friend2friend.net/modules/demo/hello-world">

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.



Interpreting a <servicereq> has 3 steps, apart from the transforms themselves.

Processing Directive Sequence

XSL transform

orCORE service

Raw

Output

Post-processed

Output

Pre-processed

Input

servicereq

Raw

Input

servicereq

Pre-processing directives:

Mid-processing directives:

pre-deserializepre-validatepre-test {,-select}pre-skippre-skip-shallowpre-update- {, -name, -namespace, -value}pre-orderpre-sort {,-data-types,-keys,-order}pre-selectpre-select-shallow

this-returnthis-validatethis-orderthis-skipthis-skip-shallowthis-update {, -name, -namespace, -value}this-sort {,-data-types, -keys, -order}this-selectthis-select-shallowthis-xml-spacethis-escapethis-escape-nodethis-insert {, -source{,-shallow}, -method}

Raw

Final Output

Post-processed

Final Output

Post-processing directives:

post-validatepost-orderpost-skippost-skip-shallowpost-update {,-name,-namespace, -value}post-sort {,-data-types, -keys, -order}post-selectpost-select-shallowpost-xml-spacepost-escape-node

Descendant

XSLstylesheet

Possible

Pre-Processing Directives

pre-deserializepre-validatepre-testpre-test-selectpre-test-select-shallowpre-orderpre-skippre-skip-shallowpre-update- {, -name, -namespace, -value}pre-sort{,-data-types, -keys, -order}pre-selectpre-select-shallow

XSL transform

orCORE service

Pre-processed

Input

servicereq

Raw

Input

servicereq

Pre-processing directives:

The following directives apply to the input document, before processing...

Mid-Processing Directives

The following directives apply to the output of the first processing step...this-returnthis-validatethis-orderthis-skipthis-skip-shallowthis-update {,-as,-namespace}this-sort {, -data-types, -keys, -order}this-selectthis-select-shallowthis-xml-spacethis-escapethis-escape-nodethis-insert {, -source{,-shallow}, -method}

First

XSL transform

orCORE service

Raw

Output

Post-processed

Output


Post-Processing Directives

Post directives apply to the final output of all servicereqs created by the original request:

post-validatepost-orderpost-skippost-skip-shallowpost-update {, -name, -namespace, -value}post-sort {,-data-types, -keys, -order}post-selectpost-select-shallowpost-xml-spacepost-escape-node

XSL transform

orCORE service

Raw

Output

Post-processed

Output


Raw

Final Output

Post-processed

Final Output

Post-processing directives:

Processing all offspring

servicereqs.

DescendantXSL

stylesheets

or

CORE

services

@pre-deserialize : Deserializing Text Nodes

This converts serialized XML back into XML:

pre

`

<servicereq function="http://friend2friend.net/services/fs-read" pre-deserialize=”//text()”><location>//false-flags.xml</location></servicereq>

@pre-deserialize= “//text()”

<servicereq function="http://friend2friend.net/services/fs-read" pre-deserialize=”//text()”><location>//false-flags.xml</location></servicereq>

@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.

@this-escape : Escaping with AttributesThis specifies which output nodes to add escaping attributes to:

mid

`

<servicereq function="http://friend2friend.net/services/fs-read" this-escape=”/*”>

<location>//example.sreq.xml</location></servicereq>

<file location="/f2f/demo/example.sreq.xml"><servicereq function="some-URI..."/>

</file>

<file f2f:escaped="*" location="/f2f/demo/example.sreq.xml"><servicereq function="some-URI..."/>

</file>

@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.

@*-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

<servicereq function="http://friend2friend.net/services/identity">

pre, mid, post

<servicereq function="http://friend2friend.net/services/identity" this-select=”//f2f:item[2]” this-skip=”//f2f:item[2]” this-order=”select skip”>

<item>Reichstag Fire</item><item>Sep 11th Attacks</item><item>Tonkin Gulf</item>

</servicereq>

@this-select= “//f2f:item[2]”

@this-skip= “//f2f:item[2]”

<item>Sep 11th Attacks</item>

@this-skip= “//f2f:item[2]”

@this-select= “//f2f:item[2]”

<item>Reichstag Fire</item><item>Tonkin Gulf</item>

Without @this-order:Without @this-order:

<item>Tonkin Gulf</item> <item>Sep 11th Attacks</item>

@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.

@*-sort, @*-sort-keys : SortingThis 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.

<item gov="DE">Reichstag Fire</item><item gov="US">Sep 11th Attacks</item><item gov="US">Tonkin Gulf</item>

<file location="/f2f/demo/false-flags.xml"><list>

<item gov="US">Sep 11th Attacks</item><item gov="US">Tonkin Gulf</item><item gov="DE">Reichstag Fire</item>

</list></file>

@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’.

`

Example of @sort - reversing Node Order*-sort-keys may use any xpath. For example, to reverse child order:

pre, mid, post

<servicereq function="http://friend2friend.net/services/fs-read" this-sort=”//f2f:list” this-sort-order=”0” this-sort-keys=”position()”>

<location>//false-flags.xml</location></servicereq>

<file location="/f2f/demo/false-flags.xml"><list>

<item gov="DE">Reichstag Fire</item><item gov="US">Sep 11th Attacks</item><item gov="US">Tonkin Gulf</item>

</list></file>

@this-sort= “//f2f:list” @this-sort-order=”0” @this-sort-keys=”position()” <file location="/f2f/demo/false-flags.xml">

<list><!-- False Fag operations →<item gov="US">Tonkin Gulf</item><item gov="US">Sep 11th Attacks</item><item gov="DE">Reichstag Fire</item>

</list></file>

@this-insert-* : Adding Input BranchesThis selects branches of input XML and appends it to the output.

mid

`

<servicereq function="http://friend2friend.net/services/fs-write" this-insert-source=”//f2f:list”>

<data><list>


</list></data><location>//false-flags.xml</location>

</servicereq>

139

139<list><item>Reichstag Fire</item><item>Sep 11th Attacks</item><item>Tonkin Gulf</item>

</list>

@this-insert-source=“/node()” @this-skip=“/node()” is analagous to the Unix tee

@this-insert-source= “//f2f:list”

@this-insert-* : Calculating XPathsIf this evaluates to a string, it is added to the output in the same way.

mid

`

<servicereq function="http://friend2friend.net/services/fs-write" this-insert-source=”concat(’ bytes, ’, count(//f2f:item),’ item(s).’)”>

<data><list>


</list></data><location>//false-flags.xml</location>

</servicereq>

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).’)”

@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

<servicereq function="http://friend2friend.net/services/fs-write" pre-test=”//f2f:item” pre-test-select=”//f2f:list”>

<data><list>

</list>

</data><location>//false-flags.xml</location>

</servicereq>

@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

<list>

</list>

@*-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, ’/’ ,.)”

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 name New namespace New value

Comments ignored ignored New value

CData ignored ignored New value

Elements New name New namespace New value

P. I.’s New name ignored New value

@*-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

`

<servicereq function="http://friend2friend.net/services/bag-read" pre-validate="*">

<itemid>some-string-id-for-a-change</itemid></servicereq>

@{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.

@*-xml-space : Preserving Whitespace

This adds an xml:space attribute to the top of the output:

mid, post

<?xml version="1.0"?>





<!-- Transform here,

which gets the

height.

--!>

`

<servicereq function="http://friend2friend.net/services/fs-read" this-xml-space="1">

<location>//example.xml</location></servicereq>

<f2f:file location=”http://friend2friend.net/services/fs-read”><some-xml-file-here>...contents...</some-xml-file-here>

</f2f:file>

<file location="/f2f/demo/example.xml"><some-xml-file-here>...contents...</some-xml-file-here>

<file>

<file location="/f2f/demo/example.xml" xml:space="preserve"><some-xml-file-here>...contents...</some-xml-file-here>

<file>

@this-xml-space is for handling whitespace sensitive files (discouraged in F2F).

@this-xml-space= “1”

<servicereq function=”http://friend2friend.net/services/fs-write” pre-skip=”f2f:data/f2f:file”> <data> <servicereq function=”http://friend2friend.net/services/fs-read” this-escape=”/*”> <location>//bad-servicereqs.xml</location> </servicereq> </data> <location>//bad-servicereqs(copy).xml</location></servicereq>

Safe Processing of Untrusted XMLA common task is to handle any XML, without interpreting any servicereqs.

<file location=”/home/f2f/bad-servicereqs(copy).xml”><bad-sreqs>

<servicereq function=”http://f2f.name/scam”/><servicereq function=”http://f2f.name/spam”/>

</bad-sreqs></file>

adds f2f:escaped=”*” at the root element(s) so the contents will not be processed.

<file location=”/home/f2f/bad-servicereqs(copy).xml” f2f:escaped=”*”><bad-sreqs>


</bad-sreqs></file>

@this-escape= “/*”

Safe Processing of Unknown XML - 2The f2f:file has f2f:escaped=“*”, so now the outer request is processed:

<servicereq function=”http://friend2friend.net/services/fs-write” pre-skip-shallow=”f2f:data/f2f:servicereq”>

<data><servicereq function=”*” escaped=”*”> <some-XML/> Won’t be interpreted because of the above.

</servicereq> </data><location>::sink.xml</location>

</servicereq>

removes the escaping item before it is processed. @pre-skip-shallow= “f2f:data/f2f:file”

<servicereq function=”http://friend2friend.net/services/fs-write” pre-skip=”f2f:data/f2f:file”><data>

<file location=”/home/f2f/bad-servicereqs(copy).xml” f2f:escaped=”*”><bad-sreqs>


</bad-sreqs></file>

</data><location>//bad-servicereqs(copy).xml</location>

</servicereq>

This request writes the data from the file without having processed its contents.

<servicereq function=”http://friend2friend.net/services/fs-write” pre-skip=”f2f:data/*/@f2f:escaped”><data>

<bad-sreqs><servicereq function=”http://f2f.name/scam”/><servicereq function=”http://f2f.name/spam”/>

</bad-sreqs></data><location>//bad-servicereqs(copy).xml</location>

</servicereq>

Summary

Recommended Follow-up: FF7: Server Structure

Their efficiency and brevity means they should be used in preference to XSLT.

@


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


a presentation by robin upton (2009-10-04) latest version at attribution – noncommercial -...

Documents

preselectshallow xsl

preprocessing directives

preorder presort

mid processing directives

default processing order

following directives

pretest pretest

processing step