Slightly-restful participating-services-list facility ( was RE: [ws-caf] [Bug 135] New: participating-services list needs to have defined semantics and modification mechanisms or be removed)

["Furniss, Peter" <Peter.Furniss@choreology.com>]

this includes (at 13) a first stab towards the lightweight referencing
specifcation for maintaining a list of participating services for an
activity, to be accessed by dereferencing the passed-by-reference
context for the activity. First it states some design assumptions, some
of which may be contradictory to the received wisdom of the TC:

1. a list of participating services (p-s) for an activity has to be
centralised or be supported by a rather complex protocol - with the
mutating context of pass by value, one would need registrations and
constant update exchanges

2. if the list is centralised, a relatively simple protocol is needed.
The centralised list needs to be informed when a service first
participates, and any entity that requires the current list of
participants can fetch it from that point.

3. At least the p-s list is therefore passed by reference, not by value.

4. to deference a context, the 0.3 spec provides a choice (in its
syntax), decided at context creation (though of course constrainable by
a ref. spec) of either a service reference for the Context Manager or a
URL that can be dereferenced directly. It is understood (this needs
tightening, I suggest) that this means the full context can be retrieved
using the Context Manager getContents or an http GET on the URL,
depending on which is provided.

5. It seems obvious that the information that a new service has been
added to the activity should be sent to the same place as the context is
held.

6. The p-s maintenance facility can be kept simpler if only one update
mechanism is used - Eric suggests we use http PUT

7. I think it has to be http POST, not PUT, since (unless we add some
additional fields to the by-reference form), it would have to be sent to
the content URL, on which GET retrieves the whole context. PUT would
mean replace the whole context (and is possibly equivalent to Context
Manager setContents, but that's another question that should be
clarified).

8. An http POST to the content URL could be specified (for a context
whose context-type determined that this mechanism was to be used) as
adding the contents of the POST to the p-s list. However, it is likely
that there will be other things that need to be added to a
context-by-reference, and the p-s maintenance system should leave space
for this. I am not sure what is the best way to do this - it could be
inferred from the type of the body of the POST, or could be by using a
derived URL for the POST, rather than the one used for GET'ing the
contents [hmm - this looks like a weakness in the REST argument - what
I'm actually trying to do is distinguish addParticipatingService from
addUserIdentification, but I'm not allowed extra methods]

9. I think (but seek guidance) that the RESTful thing to do is to add to
the contents URL for the POST, so the p-s facility must specify an
additional string (this doesn't sound at all right) so that services can
POST to a URL they can construct from the information available in the
received context.

10. According to the open content model used in ws-context, a
participating service would be identified by a service-ref, not by a
URI. The p-s facility is going to need a means of determining that two
service-ref's represent the same service. Lexical match is a sufficient
but perhaps not necessary determinant for this.  It probably won't
matter if there are unintended duplicates in the list (or, of course,
might turn out to be critical for some use-case).

11. A service could be deemed to be participating by it's immediate
client invoking on it, or by it receiving the context. It is probably
better to deem the beginning of participation the receipt of the
context, rather than the sending. (This has the implication that a
service that does NOT support the p-s facility will ignore a context
requiring it with mustUnderstand="false", and will consequently be
deemed NOT to be participating in the activity - if the client
determines participation, then such a service would be a participant
(though of course any services IT invokes could never be in the p-s
list))

12. Making the service responsible for including itself in the p-s list
means that it will identify itself by the service ref of its own
choosing, which might or might not be the same as the one used by the
client invoking it. This will affect the matching question mentioned in
10, but might contradict the purpose of the list (e.g. if the service
ref is different to the one a client uses, a client couldn't easily
check to see if a service it was contemplating using was already in the
activity)

13. Given the above considerations, the specification for p-s lists is
something like:

This specification uses WS-Context, with the following additions and
variations.

a) the context is always propagated by reference, and always uses the
content, not contextManager element.

b) the extension elements of the full context include a
participating-services-list element which is a possibly empty list of
service-ref's [this assumes we've removed the current p-s list from base
context]

c) this specification can be used as a protocol in its own right, with
no further derivation or extension to the context. In such a case, the
context type shall be [uri assigned in this specification]

d) this specification can also be used as part of a "higher" protocol,
extending the use of context further. In such a case the context type
will be determined by the higher protocol specification and there may be
additional extension elements. The higher level specifcation MUST state
that it incorporates the procedures of this specification and MUST NOT
specify variation from them except where explicitly allowed here. [if
that's not good enough for it, it can define its own mechanisms, but we
want to keep the semantics of our p-s list clear]

e) a context-service creating a context using this protocol shall ensure
that an http POST sent to the URL formed by concatenating the URL in the
content field of the context with the string "/participating-services"
with a body containing an xml service-ref element as specified in
ws-context, section 1.3 shall cause the service-ref element to be
present in the participating-services-list element of any copy of the
full context delivered as a response to any subsequent GET to the
content url. An OK (200) response shall be returned to the POST,
assuming this is successful.

f) A web service receiving, in a SOAP header, a ws-context with type [as
above] or with a type that incorporates this specification MUST, if it
"understands" the context type and has not already attempted such,
invoke a POST to the URL formed by the concatentation of the content URL
in the received contet and the string "/participating-service", and
supplying the service-ref for itself as the body of the POST.

14. Ratholes and problems:

i) there's no explicit rules there about persistence - if the "context
manager" crashes, does it remember the p-s list - in fact, does it
remember the context at all ?  That would seem to be a general question
for ctx-by-reference and the general solution can be applied here [but
needs to stated in the base spec]

ii) I elided the problem of service-ref equality for the manager by just
saying the addition must be included in the future. It's still a little
shaky though - there probably ought to be a rule that duplicates are
eliminated - but that requires definition of service-ref equality.

iii) I've ignored the possible internal race between a POST and a GET in
the manager - "subsequent" ought to have a defined leeway. Certainly any
GET arriving after the OK(200) has gone out should see the new entry

iv) I've not required the web service to wait for the OK(200) before
processing, though it probably should. What if it can't get through to
the "manager" or gets a non-OK reply - should it fault the service
invocation. That could be left as an explicit switch for a referencing
spec (of this spec), with a default. If set to "don't wait, don't'
fault" then the p-s list is only a best-effort list. If a fault is
expected, this spec should probably define it.

15. Comments welcome, but I expect an equivalent level of detail in
counter-proposals. Apart from the obvious "there is no use-case for
this, don't do it and take the field out of the base context". :-)   I'd
especially welcome comment on whether the solution in 9 is the RESTful
way - and if it isn't whether there actually is a RESTful way that
doesn't involve extra round trips or extra fields in the propagated
context.

Peter