[Oslc-Automation] Action resources - implementation patterns

Mon Jan 6 09:48:32 EST 2014

Response inline

Kind regards,

Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
Open Services for Lifecycle Collaboration - Automation WG joint chair

E-mail: martinpain at uk.ibm.com
Find me on:  and within IBM on:  

IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU

"Oslc-Automation" <oslc-automation-bounces at open-services.net> wrote on 
27/12/2013 19:03:32:

> From: John Arwe <johnarwe at us.ibm.com>
> To: oslc-automation at open-services.net, 
> Date: 27/12/2013 19:03
> Subject: Re: [Oslc-Automation] Action resources - implementation 
patterns
> Sent by: "Oslc-Automation" <oslc-automation-bounces at open-services.net>
> 
> I did a reasonably slow, focused, top-to-bottom read of the Core 
> Actions draft, and made some updates over the past 2 days.  I think 
> we're getting really close. 
> 
> The 12/26 edits should be completely non-controversial. Typo, adding
> links, etc. 
> Today(12/27)'s edits are very likely non-controversial.  Smaller-
> scale cleanup of certain sections.  Probably worth a look from 
> Martin to be sure I didn't accidentally vary from his intent. 
> The big-animal outstanding questions/comments I had are listed below. 

> 1:  Secondary bindings: I think we should cover that entirely in 
> Automation, not Core. 
> 1a: Let Core be about Actions -- the parts that multiple parties 
> need (UI introspection, bindings, and "execute now" discovery).  The
> only thing I'd leave in Core around delayed execution is the 
> interaction pattern heading, and make its content consists entirely 
> of text (probably non-normative) pointing to Automation as having 
> defined such an interaction pattern. 
> 1b: Let Automation cover the delayed execution angle.  That's the 
> only place the need has arisen.  Any "complications" like secondary 
> bindings it can pay for, rather than obscuring further what Core is 
> doing.  It's every bit as re-usable from Automation as from Core. 

No objections

> 1c: Secondary bindings might become "immediate execution action 
> bindings" instead.  Once they're relegated to Automation, it's 
> harder to confuse them with Core's bindings ;-) 
> 1d: I think Automation (when it defines delayed execution's pattern)
> states (as part of that pattern) which existing action bindings are/
> not allowed as secondary bindings, along with any additional 
> constraints those usages have.  If we can't do that, something is 
> fundamentally wrong.  I.e. if the only way to define the zero-body 
> http request interaction pattern (or any other in Core) so that it 
> "works right" when we later want to add a delayed execution 
> interaction pattern is to know about the future when defining zero-
> body, we're toast already.  Automation will need some generic 
> statement like "we're silent on; might work, might not" to cover 
> cases where new Core patterns/bindings/profiles are added in the 
> future, but that's life in the big city. 

OK

> 1e: In the existing "Use for secondary bindings" text, there is a 
> consistently repeated phrase "then it is to behave like" ... am I 
> correct in thinking that one is expected to read "it is" as a normative 
MUST?

Yes. Updated wiki.

> 2: In the final paragraph of [1], a statement is made: "However, as 
> already stated, implementations MUST NOT rely on this behaviour from
> other implementations".  I was going to lowercase the must-not 
> (since it's a restatement), and make the bulk of that text a 
> hyperlink to the original, but I'm unclear after reading it what 
> it's referring so I cannot create the link.  It might be referring 
> to the beginning of the same paragraph (which has a MUST NOT); I 
> cannot be sure what the final sentence's "this" refers to. 

"This" refers to the SHOULD in that same paragraph. The "already stated" 
does, as you guessed" refer to the "MUSt NOT" at the beginning of that 
paragraph. The final sentence is to emphasise to consumers that the SHOULD 
on the providers is a SHOULD not a MUST, and therefore cannot be relied 
on.

> 3: In the RDF body pattern [4], we say "It is possible for bindings 
> to match the identification rule of both the HTTP request with empty
> body pattern and this pattern."  I don't think that's actually true;
> the zero-body pattern [3] says " MUST have an rdf:type value of 
http:Request
> , and MUST have an http:body value of rdf:nil.", whereas the RDF 
> body pattern says "MUST have an http:body property whose target 
> resource:" ...other constraints that rule out rdf:nil. 

They do not say that the bindings "MUST have a single http:body property, 
which MUST have a single rdf:type value of...".

In other words, a single http:Request binding may have two http:body 
properties, one of which could have the value rdf:nil, and the other could 
match the "HTTP request with RDF body" rule. This would match both rules, 
as it both has "an http:body value of rdf:nil" and has "an http:body 
property whose target resource [matches the other constraints]".

I have now attempted to make this explicit in the "It is possible for 
bindings to match [both]" paragraph.

> 4: In the RDF body pattern [4] and resource shape pattern [2], we 
> say "It is possible for bindings to match the identification rule of
> both the HTTP request with empty body pattern and this pattern."  In
> that context "bindings" (plural) could mean "different bindings on 
> the same Action resource", but I think the intent might have been 
> "each [or: a single] binding".  I was not sure enough to update it 
> on the wiki however, given that others will be reading that possibly
> in parallel. 

"a binding" (each binding/a single binding) would be correct. I have 
updated the text to say "a binding".

> 5: In the resource shape pattern [2], we say "finding or 
> constructing an RDF resource that matches the defined resource shape
> and using an appropriate serialisation of that resource as the HTTP 
> request body."  I don't see how a client is going to know which 
> serialization(s) are "appropriate", and given that this is an input 
> we'd certainly *like* it to be both concrete and asserted (Content-
> Type: header) on the request rather than relying on the provider 
> (recipient) engaging in content-sniffing or on out of band means. 
> We could use http:headerName etc for that; doing so would require 
> changes to Appendix A's "common restrictions" [5].  The RDF body 
> pattern [4] has the same issue.

My intentions were:
A) I'd expect that all communications between the client and server
   so far have probably used a single serialization/format. This is
   the one I'd consider "appropriate". However, looking for
   Accept-Post headers might also be appropriate.
B) I would expect the consumers to set the Content-Type header. We
   should state this explicitly.

I've attempted to clarify both of these in the text.

> 6: In the RDF body pattern [4], I'm not sure what the extra(?) level
> of indirection through oslc:ContentAsRDF buys us.  Is this simply to
> follow the patten of [6]? 

Without it, we are defining the meaning of allresources linked to by the 
http:body predicate. However this predicate is not under our control.
Without the level of indirection, our definition of http:body would mean 
that if a provider used a content:ContentAsText resource with the 
intention of specifying a literal body, then what our spec would be saying 
is "POST a representation of the ContentAsText resource as RDF", rather 
than the provider's intention to "POST the text within the ContentAsText 
resource as text/plain".
While we could provide explicit exemptions for the RDF classes that we 
currently know of that can specify content, it seems better to follow the 
pattern that they've already set and attach these "serialize as RDF" 
semantics to an RDF class created for that purpose. This way we allow for 
other future ways of specifying content, and stand a better chance of 
being compatible with other uses of the http vocabulary.

> 7: The Automation pattern [7] made reference to "the HTTP request 
> pattern" (sic), which no longer exists.  I think from the context it
> intended to say "request with RDF body" i.e. [4], so I did create 
> that link (just in case I guessed wrong, others now know).  The same
> case+fix arose in [9]. 

That is correct.

> 8: In the final bullet of [8], we talk about something that sounds 
> like a server implementation issue.  If that's the case, seems like 
> a Best Practice (at most), not normative text. 

I've had more thoughts about this, and removing this point would help the 
scenario where the user uses a dialog configure an action before the 
resource exists. So I'm happy to remove it (and have now done so).

However, it is not entirely a server implementation issue, as it means 
that everything else (the template Automation Request, the Creation 
Factory or dialog URL) could be replaced with others found on the service 
provider (allowing for flexibility in how the request body is constructed) 
- the only thing that needs to remain constant is the Plan URL. However, I 
will leave it to the scenarios to drive this if needed.

> 9: In the delayed execution pattern [10], [11] left me in the dust 
> (I saw no sign of this in the examples or ODT, either). 
> Conceptually I'm "sure" I know what you're saying, it's simply 
> omitted syntax/examples I think. 

This should be simplified when we can list all the valid patterns for 
execution-time (secondary) bindings in one place, as you suggested above. 

> 10: The construction of Appendix A [12] seemed at odds with itself. 
> In the first section: "a consumer MUST...include the headers specified 
by the 
> http:headers property, if present", and in the second section 
> "providers MUST provide bindings that:    do NOT include the 
http:headers
> property".  This might be smart spec factoring if we're trying to 
> separate "simple profile" constraints from "support all of http:Request
".

The second section is one that may be included by specific profiles. It 
does not apply unless a profile explicitly includes it (I have updated it 
to state this). The first half is intended to "support all of http:Request
".

In any case, these are not contradictory - the second section is intended 
to require providers to offer at least onebinding per action that meets 
these conditions, not imposing these conditions on all bindings (again, 
I've tried to make this clearer). Therefore these restrictions allow 
consumers to either be programmed to only find and use the ones with no 
header values, or to understand how to parse and use the header values, 
and so be able to use them if present.

> 10a: If consumers are required to support http:headers anyway, then 
> this must be about saving providers' implementation budgets.  But 
> that's in their own best interests anyway, so what do we gain again?
> Promising consumers that we'll never use the code we just said they 
> had to write?  FWIW I've (recently) seen implementations completely 
> dependent on extension headers for authentication; although that 
> "just" means they'd need to define profile(s) instead of re-using these. 

Consumers only need to support http:headers if the profile they are 
written against does not include these restrictions. If they are using a 
profile that includes these restrictions, then all they have to do is 
check that no http:headers are present (as these restrictions require that 
each action will have at least one binding that does not use any headers - 
but it may have other bindings that do in addition).
I'll have a go at re-wording this to better communicate my intentions, but 
it's possible we're not gaining much.

> 10b: [12] end first section says "Note: If OSLC implementors want to
> specify literal HTTP request bodies (which are not covered by any 
> interaction patterns in this specification)"  I think that's no 
> longer true (RDF body?), or did you mean something different by 
> "literal body"? 

By "literal body" I mean something like text/plain (or binary data), e.g. 
:

    POST /actions
    Content-Type: text/plain

    action=delete&resource=1

Other responses to recent changes:

11. In the "what are actions?" section [13] it now says "without knowing 
anything about R other than its URI and (perhaps) how to construct HTTP 
requests given instructions". However, "how to construct HTTP requests 
given instructions" is not really "about R". Unless you mean "consumers 
must be able to retrieve R's triples".

12. Not related to your changes, but we have a "MUST" in the "providers" 
section [14] under the "Overview (informative)" section [15]. There is an 
equivalent MUST under the "instruction for executing currently available 
actions" section [16], so I've just removed the bold markup from the one 
in the informative section.

13. Under "instructions for executing currently available actions" [16] 
these words: "A consumer executes an action by following a single 
interaction pattern that it supports, and applying information supplied in 
the action binding to the pattern. A consumer MAY use any interaction 
pattern whose identification rule is matched by the action binding. " seem 
to suggest that a consumer MAY use an interaction pattern that it supports 
even if its rule did not match. Otherwise what is that MAY saying other 
than that they also might not? While it does not make sense for consumers 
to do so, should we include a MUST somewhere? e.g. "A consumer MUST use 
one of the interaction pattern(s) whose identification rules are matched 
by the action binding it has chosen."?

[13] 
http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-RDF-resources/#What-are-actions
[14] 
http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-RDF-resources/#Providers
[15] 
http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-RDF-resources/#Overview-informative
[16] 
http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-RDF-resources/#Instructions-for-executing-currently-available-actions

> [1] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#Types-of-actions 
> [2] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#pattern-resource-shape 
> [3] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#pattern-empty-body 
> [4] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#pattern-rdf-body 
> [5] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#Standard-restrictions-on-http.3ARequest-resources-
> for-simple-specification-profiles 
> [6] http://www.w3.org/TR/Content-in-RDF/#ContentClass 
> [7] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#pattern-autoreq 
> [8] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#Additional-provider-constraints 
> [9] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#Execution_3 
> [10] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#pattern-dialog-delayed-execution 
> [11] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#Additional-provider-constraints_1 
> [12] http://open-services.net/wiki/core/Exposing-arbitrary-actions-
> on-RDF-resources/#constructing-http-requests 
> Best Regards, John
> 
> Voice US 845-435-9470  BluePages 
> Tivoli OSLC Lead - Show me the Scenario 
> _______________________________________________
> Oslc-Automation mailing list
> Oslc-Automation at open-services.net
> 
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140106/8c6823ea/attachment-0003.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 518 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140106/8c6823ea/attachment.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 1208 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140106/8c6823ea/attachment-0001.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/gif
Size: 360 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140106/8c6823ea/attachment.gif>