Forgot to mention that this was submitted by a member of the OASIS
Technical Advisory Board.
bill cox
--
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
|