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


Help: OASIS Mailing Lists Help | MarkMail Help

sca-assembly-comment message

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

Subject: Re: [sca-assembly-comment] Comments on Public Review Draft 01

Forgot to mention that this was submitted by a member of the OASIS Technical Advisory Board.

bill cox
William Cox
Email: wtcox@CoxSoftwareArchitects.com
Web: http://www.CoxSoftwareArchitects.com
+1 862 485 3696 mobile
+1 908 277 3460 fax

William Cox wrote:
4A4191B8.5070009@CoxSoftwareArchitects.com" type="cite">Comment numbers in square brackets. References are to the PDF.

[0] General

I'll start by agreeing with the positive comments that Jacques Durand made in previous messages to this list. Also, the use of conformance assertions is excellent and very useful to implementers and users alike.

[1] Editorial Lines 63-75 and general

The typographical conventions are hard to unravel (unless there's a reference to a document that describes it). The C++  Spec does better on lits lines 35-52, with separate naming conventions. However, a description of the convention for indicating conformance assertions is needed as well--when we see the first one we wonder "what's that? A reference?" The typographic appearance of the section is very different from that in the C++ spec.

The major sections should start on an odd page.

The yellow highlighting on Conformance Assertions differs  from that in the C++ document. This should be consistent across all documents for SCA.  (the highlight  is a bit hard to read in grayscale, but I'd rather have it than not).

The color in the XML snippets is very useful, but very hard to read on a grayscale printer. I suggest using bold to make it work both ways.

Names and acronyms should be defined at first use. E.g., line 137, "Promote" is capitalized, but is the first occurrence. It appears to have some specific meaning from Figure 2, but there is no explanation. Intent is used without definition (looking at lines 173-175 there's no definition, and the link takes me to the same page. The implied reference to the SCA Policy Framework should be made in the Overview.

[2] Editorial Lines 1-62

The terms "next part", "final part" are confusing. Use the final section numbers, please.

The references should be consistently numbers or (preferably) names/abbreviations. The numbers are confusing when reading.

Reference [8] is to a TC not to a specific Committee Draft; correc to show which document is being used as a normative reference.

The references do not line up vertically.

[3] Technical Lines 1-62

I was surprised to not see a reference to the SOA Reference Model, which standardizes some of the terminology used. Add a reference.

Is there an overview document that could be referenced? The introductory material could be shared among documents by normative reference. The relationship to the SCA Policy Framework is not clear; perhaps I'm missing such a base document?  Perhaps appendix B (Normative) is intended to serve this purpose, but it's not referenced here, and

[3] Technical Lines 76-125 and 587ff

What is the relationship to (e.g.) BPMN? The BPEL relationship is apparently in the BPEL document, but an overview shouuld mention a relationship (if only to state there is none).

The use of "services" (not in bold italic" and components is confusing in this overview.

The description of composites (lines 104 ff) is not consistent with lines 589 -- I was surprised to find that a composite could be empty. Jacques Durand's comment 9 and 11b are relevant here.

The additional fact that a composite may have "zero or more component elements within a composite." is confusing.  The motivation for empty composites and for the non-exposure of components needs to be explained so it can be reviewed.

[4] Technical General

The uniqueness of names across all service elements of a component type (lines 257-259) and  at various levels (e.g. line 1366) would seem to be a burden. I assume the the rationale is that within a particular level of container (and with URIs) you require uniqueness. That architectural choice should be made clear in the introduction and perhaps the first time referenced. A designer might want components serving a similar function to have the same name in different composites; why should that not be permittted? "AccountConsolidator1", AccountConsolidator2" don't appear to be good names.

If there is good reason for the architectural choice, it should be stated; workarounds in practice should be described or considered.

[5] Technical Lines 2266ff (section 6)

The motivation for constrainingType is not clear. This appears to be some sort of templating mechanism for yet-to-be-defined details. This is a good goal, but why this mechanisms.

"constrainingType" is misspelled on line 2314.

[6] Technical Section 7

I found the introduction of section 7.2 (long running request response operations) to put low level networking issues into SCA. It appears to be necessary, but an overview for Section 7 would help.

Line 2401 has "Error! Reference source not found".

The opening paragraphs of Section 7 could be more clear: the relatoinship between services (which have one interface) and the operations (one or more per interface) and operations would be more clear with a picture showing the multiple relationships, I believe.

The relationship to (e.g.) BPMN and BPEL may illuminate the choices and the specification here.

[7] Technical Section 11 lines 3327ff

Perhaps the overview document I didn't locate (no normative or non-normative reference) would explain the similarity in these issues to WAR/EAR files, and motivate the terminology.
[8] Editorial line 2284

"Error! Reference not found"

[9] Conformance lines 3826ff

The conformance section is one of the best I've read. The links to conformance assertions is very effective. A reference in lines 3827-3837 to Appendix C would be helpful, as would the typographical conventions I discussed in my Comment [1]. The highlighting is very useful, and should be adopted in other SCA specifications.

[10] Technical Appendix B lines 4652ff

This is good to have in e document, but it needs to be referenced in the introduction. Where would I find in this that composites can be empty and the similarities to Components? I separate architectural white paper (which may well exist) could be referenced.

This document is excellent overall; congratulations on a work well progressed!

bill cox
William Cox
Email: wtcox@CoxSoftwareArchitects.com
Web: http://www.CoxSoftwareArchitects.com
+1 862 485 3696 mobile
+1 908 277 3460 fax

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