OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

sca-assembly message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [sca-assembly] Comments on impl-type-documentation-wd05 & new wd06version...



Eric,

Many thanks for the review - comments inline

I think I've dealt with each one positively, bar one, for which you may want to raise an issue.

I've created a wd06 version of the implementation type document which I have posted here:

http://www.oasis-open.org/apps/org/workgroup/sca-assembly/download.php/38495/sca-assembly-1.1-impl-type-documentation-wd06.odt
http://www.oasis-open.org/apps/org/workgroup/sca-assembly/download.php/38496/sca-assembly-1.1-impl-type-documentation-wd06.pdf

Yours,  Mike.

Strategist - Emerging Technologies, SCA & SDO.
Co Chair OASIS SCA Assembly TC.
IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  
Email:  mike_edwards@uk.ibm.com



From: Eric Johnson <eric@tibco.com>
To: OASIS Assembly <sca-assembly@lists.oasis-open.org>
Date: 18/06/2010 21:43
Subject: [sca-assembly] Comments on impl-type-documentation-wd05





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
- Done
Need non-normative references SCA-SPRING, SCA-JEE
- Done
p. 6, section 2, line 49: extra space "produced  examples"
- Done
p. 7, section 2.1, line, 105, use of word "namespace" without reference to "Namespaces in XML" specification.
- Done
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."
- Hmm.  I don't agree here. In Java, for example, Annotations are now a fundamental part of the language.  They are not extensions or libraries.  But an SCA-specific Annotation IS an SCA extension of the Java language (and we have LOTS of them  ;-) ).

It is difficult to come up with wording that applies naturally to any implementation language so I've added the words ", libraries (and so on)" after the words "existing features" as an attempt to hint at the generality of aspects that the paragraph is trying to cover.
p. 9, section 2.4, line 229, IMP10012,  End of sentence should be "... artifacts described by the implementation type element".

- Adjusted the wording, although in a different way to the suggestion
p. 10, section 2.5, line 250, delete "essentially"

- replaced with "at minimum"
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."
- Done
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 ..."
- Done
p 8, section 2.1, line 160 - Additional "SHOULD": "Implementation type elements SHOULD allow for extension via the XML Schema "any" and "anyAttribute" constructs.
- Added [IMP10032]
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.
- Added [IMP10033] to indicate that non-support of those features must be documented.  Also added statement with strong recommendation that support for these features is provided.
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.
- We discussed this on one of the TC calls, but let me repeat here for anyone who did not hear the discussion.
I believe that the Assembly spec demands that any remotable interface is capable of being mapped to WSDL 1.1.
- the demands are made in Section 6.2 on interface compatibility - point #6 in 6.2.1, in 6.2.2 and in 6.2.3
- compatible interfaces are then part of numbers of other normative statements, using the content of 6.2 as definitional material

The result of this is that for remotable interfaces, mapping to WSDL 1.1 must be supported.

You are welcome to raise an issue against the Assembly spec to change this approach, but my reading says that WSDL 1.1 mapping is a requirement and that this was explicit and intentional when the Assembly spec was created.

p. 11, section 2.5, line 310 - Additional "SHOULD": "Implementation type elements SHOULD allow for extension via the XML Schema "any" and "anyAttribute" constructs.
- Added [IMP10034]
p. 11 - at end - here is missing any description of how a new interface MUST describe its mapping to at least one binding.
- I note that nowhere do we describe this for any existing interface type.  What would such a description look like?
- I also note that nowhere do we have a description of how an IMPLEMENTATION type maps to any binding, but it is clear from an SCA runtime
implementation like Tuscany that the binding implementation must have a way of linking to the implementation instance artifacts, although this is
done in a rather generic way in Tuscany.  This may possibly be something that you can raise as an issue against the Assembly spec, but perhaps
a mailing list discussion would be appropriate first.
p. 12 - section 2.6, lines 344-345 - appear to be missing any normative statements about descriptions of how export works.
- Adjusted the wording of [IMP10027] so that it clearly encompasses both export and import of artifacts
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

- I added material in 349/350 which describes extension and references the example of the one in the Java POJO spec.

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?
- I've added a new section and 2 additional normative statements for this - [IMP10036], [IMP10037]
Any description of what error handling means.

- I've added a new section and one additional normative statement for this [IMP10035]

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








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








[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]