Comments on impl-type-documentation-wd05

[Eric Johnson <eric@tibco.com>]

I've just finished a review of the impl-type-documentation-wd05, and I have collected the following requirements.

There are obviously editorial items, and then there are issues that should be raised.

I've put them in this form first to see whether there's strong disagreement that something is an issue, or if something is border-line, perhaps it can be handled editorial.  All comments are from the PDF form, to avoid cross-platform confusion.

Editorial:

p. 5, section 1.2
Normative references needed: XML Schema, Namespaces In XML

Need non-normative references SCA-SPRING, SCA-JEE

p. 6, section 2, line 49: extra space "produced  examples"

p. 7, section 2.1, line, 105, use of word "namespace" without reference to "Namespaces in XML" specification.

p. 9, section 2.3, line 213: the word "language" here is suspect.  What the rest of the paragraph refers to - annotations and additional libraries/APIs, are not extensions to the language, but rather extensions to the libraries for the language.  What might work better is "language support libraries."

p. 9, section 2.4, line 229, IMP10012,  End of sentence should be "... artifacts described by the implementation type element".

p. 10, section 2.5, line 250, delete "essentially"

Substantive:

p. 7, section 2.1 line 106, add a sentence: "The formal name of of the implementation type is the Qualified Name of the XML element."

p. 7, section 2.1, lines 115-117: Change to read: "Formally, the XML Schema definition of the implementation extension belongs to the substitution group of the <sca:implementation/> element ..."

p 8, section 2.1, line 160 - Additional "SHOULD": "Implementation type elements SHOULD allow for extension via the XML Schema "any" and "anyAttribute" constructs.

p. 9, section 2.2.1, line 210: Question: may an implementation type simply declare that it supports neither bi-di interfaces, nor long-running requests?  I think the answer is "yes", and it is worth stating that.  The currently language here allows for this exclusion, but is somewhat weaselly on the subject.

p. 10, section 2.5, lines 252 & 253.  The statement IMP10030 is not supported by any existing requirements in SCA Assembly, and should not be added here.  Per the existing Assembly language, "remotable" does not imply WSDL 1.1 mapping, and therefore not all remotable interfaces need to map to interface.wsdl.  In fact, it could be quite desirable for some new implementation type to map to some new interface such as interface.wsdl20, just to pick a random example.

p. 11, section 2.5, line 310 - Additional "SHOULD": "Implementation type elements SHOULD allow for extension via the XML Schema "any" and "anyAttribute" constructs.

p. 11 - at end - here is missing any description of how a new interface MUST describe its mapping to at least one binding.

p. 12 - section 2.6, lines 344-345 - appear to be missing any normative statements about descriptions of how export works.

p. 12, 13, section 2.6/2.6.1: Currently says
line 349-350: "It is recomended that an extension of the base mechanism is used."

lines 382-384: "If using an extension of the base SCA mechanism for imports and exports, the implementation type documentation must define import and export elements that extend the base Import and Export types. [IMP10028]

These statements are, of course, different, in that one is about mechanism of the behavior, and the other is about type definition of the XML Schema elements.  However, it struck me as somewhat confusing to have them not quiet proximate to each other in the specification, and both using the notion of "extension".  It would help me if someone could clarify what an extension of the base mechanism might mean.

Overall missing items:

Any description of policy related constructs.  If the implementation type derives the component type, then how are policy & policy set derived?  Are there any specific policies or policy intents relevant to the implementation type?  If so, how?

Any description of what error handling means.

-Eric.

P.S.
Side note for any of you on the Java TC - a brief traipsing through the CI spec (HTML form)shows exactly two hits for the word error:

• "Error! Reference source not found" and
• JCI80002

... and not a single use of the word "Exception".  I find this lack of discussion of error & exception handling surprising.  Not knowing whether you've had discussions about this, I merely observe the omission, and I leave it to TC members to figure out what, if any actions are appropriate.