[Fwd: Comments on WS-Context]

[Greg Pavlik <greg.pavlik@oracle.com>]

-------- Original Message --------
Subject: 	Comments on WS-Context
Date: 	Wed, 19 Jan 2005 14:54:38 -0800
From: 	Anish Karmarkar <Anish.Karmarkar@oracle.com>
To: 	ws-caf@lists.oasis-open.org



Hi CAF-ers,

Below are my comments on WS-Context version 0.8, 3 Nov 2004 Committee
Draft. Most of the comments are editorial/typographic/typos/spec-ese.
But a few are slightly more significant. I have not made an attempt to
classify the comments as significant/editorial but have listed my
comments in spec-lexical order.

I do realize that the comment period for the CD has elapsed, but thought 
I would send it anyway.

HTH.

-Anish
--

----------
Comments on WS-Context CD version 0.8, 3 November 2004.

1) The normative WSDL (and schema) is a separate file, which is good as
tools can access just the WSDL and process it. But the same normative
WSDL (and schema) should be included in an appendix to make the spec
complete. If using XML, this will require just a simple tweak to the XSL
(and result in just one WSDL source -- reducing maintenance problems).

2) The spec does not use the standard OASIS format which contains line
numbers.

3) Section 1 is missing, the spec starts straight with 1.1

4) Appendix A should not be section 9?

5) In "Note on terminology" it says:
"Namespace URIs of the general form "some-URI" represents some
application-dependent or
context-dependent URI as defined in RFC 2396 [3]."

Replace "some-URI" with "http://example.org/..."; and
"http://example.com/...";

6) Section 1.1.1 Prefix Namespace table should be expanded to include
the prefix "soapbind" and "soap" and an entry for wsrm referencing
scheme. Also the prefix "tns" has the namespace "targetNamespace. The
tns entry should be moved outside the table with an explanation since
"targetNamespace" is not a namespace URI.

7) Section 2, line 2:
s/operations/interactions

8) Page 6, line 2 talks about SOAP messages. Is the spec independent of
SOAP? It certainly seems like it is independent of SOAP, but there are
stmts like the one on page 6, line 2 which leads one to believe that
this is meant only for SOAP. If the core part of Context is independent
of SOAP then it would help to clarify this and specify a SOAP mapping in
a separate section. It would also help to make some statements about
SOAP 1.1 as well as SOAP 1.2.

9) Section 2.2, page 6 does not say anything about WSDL 2.0. It would be
good to separate WSDL 1.1 and 2.0. The normative WSDL is indeed 1.1, but
the wordings in section 2.2 talk about WSDL generically.

10) Section 2.3 (page 6), refers to WS-CAF. This is the first reference
to WS-CAF. It will throw-off the reader unless she knows the name of the
TC. Suggestion: s/WS-CAF/this specification

11) Figure 1 (page 6), the title "service-ref Element" is incorrect.
There is only a complexType defined in the figure.

11) Figures/XML snippets typos: some of the xml/wsdl/soap snippets are
not valid XML. Verifying the examples with a parser would help avoid typos.
Examples of invalid example:
page 6, figure 1, last line (closing '>' missing)
page 9, figure 5, 6th line (invalid schema type)

12) Consistent indentation in the examples would help readability.

13) In the spec text using a different font/bold/italics/emphasis for
XML element names/attributes would also help readability. It would also
help to prefix the element names/attributes with the "ctx:" prefix (or
whatever is appropriate).

14) page 7, first para refers to "WSRef defined in WS-Addressing" (WSRef
is used again in the following para as well). I suspect the first
occurrence really means wsrm-ref:reference-scheme and the second
occurrence means a 'Web service reference'.

15) page 7, 2st para:
s/reference schema/wsrf-ref:reference-scheme

16) Figure 3, page 7:

17) Figure 3 and figure 4, page 7, it is not clear what the prefix "ex:"
refers.

18) Page 7, para right below figure 4 says:
"A service that requires a service reference
element MUST use the mustUnderstand attribute for the SOAP header
element within which it is enclosed and MUST return a mustUnderstand
SOAP fault if the reference element isn’t present and understood."

I don't understand what this means. How does MU header help here?

19) It seems like the design point of the spec is one-way messaging
which certainly makes sense. But the normative WSDL that is provided
essentially prevents someone from using SOAP-over-HTTP request-response
MEP. For some operations like get timeout this may indeed be feasible.
Is that really the intent?

20) page 8 is blank

21) page 9, bullet regd context-manager -- It is not clear whether this
element is required to be present if it is pass-by-reference. It is
clear that if this element is present then it is pass-by-reference.

22) page 9, bullet regd timeout -- what are the units here? seconds? Why
not dateTime? Or option for both?

23) page 9, bullet regd wsu:Id -- why is this needed. Why not have
attribute extensibility (xs:anyAttribute) and leave it at that.

24) figure 5, page 9 -- why is element extensibility (xs:any) at the
beginning of the sequence? The norm is to place element extensibility at
the end of the sequence.

25) figure 6, page 10 -- having arrow-heads on the lines would help
readability.

26) page 10, para below figure 6 says:
"If the context-manager is dereferenced, it MUST return the entire
current contents of the context, i.e. the values corresponding to the
context’s ContextType elements held by the context service at the point
of receiving the dereference message."

Seems too strict. How about:
When the context-manager is successfully dereferenced to get the
contents of the context, the context-manager MUST return the ....
OR
If the context-manager is dereferenced to get the contents of the
context, the context-manager MUST return the current contents of the
context or fault, i.e. ...

The concern is that the stmt as stated in the spec is too broad. It does
not take into account the fact that the invoker may not have the right
priveledges or some other security related problem.

27) page 10 says:
"A service that receives less than the minimum context MUST return a
mustUnderstand exception when the mustUnderstand attribute is present."

Why? This seems like an abuse of MU fault. Or is this talking about a
ws-context specific MU fault. I assumed it meant a SOAP MU fault.

28) section 3.1, page 10 says:
"As mentioned earlier, ..."
include a ref to the right section.

29) section 3.1, page 10 says:
"These semantics are indicated in a context by a protocol identifier
representing the protocol type of the activity."

add "by the ctx:type element" for clarity.

30) page 11, 2nd para leads me to believe that multiple ws-context SOAP
header blocks are allowed in a SOAP env. Is that correct?

31) page 11, 3rd para:
s/which may be/which may vary from

32) Section 3.2, page 11
There seems to be some misunderstanding of how soap MUs work. A SOAP MU
says to the actor/recipient that you must understand what this header
block means which typically means understanding the header block QName
and recognizing what the spec related to the QName requires the
processor to do. It is possible that while processing the header block
there may be problems/faults such as not understanding the identifier
type (which is an extensibility point in the header block). In such
cases, the process will throw some header block specific fault and not
an MU fault.

33) figure 7, page 12
Extraneous 'CTX' in the title

34) figure 7, page 12
All application specific URI should use http://example.org/... or
http://example.com/... URIs and not http://docs.oasis.org/... URIs

35) Section 4, page 13, reword line one.

36) page 13, 1st note: add a forward reference to the right section

37) Figure 8, page 13, the dotted arrow is titled "context generated"
this title is misleading. It should be "Context Manager generated"

38) page 13, 1st bullet (regd getContents): s/it/ContextManager

39) page 13, 1st bullet (regd getContents): where are the faults sent?
To the same place as where the context contents would have been sent? Or
is this binding/MEP dependent? I assume that this is binding/mep dependent.

40) I assume that for the context-manager operations some form of
message correlation is required (part of the call-back mechanism). I.e.,
[Relationship] property in WS-Addressing or RelatesTo property in
WS-MessageDelivery. This would also require that message identifiers
also be present.

41) Figure 9, page 14: it seems odd to define a separate message type
and an operation for every fault. Can this be combined into one?

42) Section 5.1, page 15 says:
"... there is no notion of automatically informing services when a
specific state is entered"
It would be worthwhile to mention that other specs may define how this
is done and as far as this spec goes it is out-of-scope.

43) Section 5.1, page 15, 1st para below the XML snippet says:
"The namespace attribute is used by referencing specifications to
qualify the value of the status string."
Why is this a NS rather then just a URI. If the status value are
namespace qualified then why not have then as QNames?

44) Section 5.1, page 15: given that the namespace attribute is
optional, what happens if it is not specified? Are the values specified
in the spec (activity.status.ACTIVE etc) in no-namespace?

45) Need more example soap messages for context manager and context
service (at least in the appendix) -- would help readability/understanding.

46) section 5.2, page 16 says:
"Since the Context Service maintains information on multiple activities,
an activity context MAY be present on some operation invocations to
determine the appropriate activity on which to operate."

Why is the activity context not always required? How the the service
figure out the context with it?

47) Section 5.2, page 16 the text uses the terms UserCTXService and
CTXService where as figure 11 uses UserCTXServicePortType and
CTXServicePortType.

48) Section 5.2, page 16, last sentence:
s/we shall describe the interactions in the following section/the
interactions are described in the following section

49) Page 17, bullet regd (UserCTXService):
a) It is not specified which operations in UserCTX correspond to which
operations in CTXService (other than being obvious from the names)
b) It seems strange to define an operation for every fault. Can this be
combined.
c) There is no explanation for the fault operations.
d) What is special about no permission faults? There are several
security related faults that can occur. It is not clear why no
permission fault is the only one included.
e) How are faults that are not listed in the spec dealt with -- is there
a generic fault operation?

50) Page 17, begin:
s/If nesting of activities is not supported by the implementation/If
nesting of activities is not supported by the implementation and there
is a nested context specified

51) page 17, begin:
What fault is thrown if -1 is specified for timeout and the
implementation does not support the semantics of -1? Is it
timeOutOfRangeFault? If so, the name of the fault is misleading.

52) page 18 and 19:
A better name for 'setTimeout' and 'getTimeout' operations would be
'setDefaultTimeout' and 'getDefaultTimeout'

53) page 19, getTimeout says:
"This need not be the value associated with the current Activity, however."
It is unclear what 'current Activity' means here.

54) Section 6, page 20, 2nd line:
s/SOAP header/SOAP header block

55) Section 6, page 20:
Why is wsu:Id special? Why not use attribute extensibility?

56) Section 6, page 20 says:
"In addition to any authorization checks it may perform on the sender of
a message, it is RECOMMENDED that applications services perform checks
that contexts were created by authorized issuing authorities."

Is there any guidance that can be provided here?

57) Section 7, page 21 says:
"All messages based on the normative WSDL provided in this specification
MUST be augmented by a Web services addressing specification to support
callback-style message exchange."

The normative WSDL is not included in the spec.

----------