sca-assembly message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Fw: [sca-assembly-comment] Comments on Public Review Draft 01
- From: Mike Edwards <mike_edwards@uk.ibm.com>
- To: "OASIS Assembly" <sca-assembly@lists.oasis-open.org>
- Date: Wed, 24 Jun 2009 09:12:52 +0100
Folks,
I have marked up the following set of
comments on the Assembly spec as <Editorial> for editorial comments,
which I think
should be logged as a single issue,
and <Issue n>
for substantive comments which I think should each be raised as a separate
issue for tracking purposes.
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
----- Forwarded by Mike
Edwards/UK/IBM on 24/06/2009 09:02 -----
From:
| William Cox <wtcox@CoxSoftwareArchitects.com>
|
To:
| sca-assembly-comment@lists.oasis-open.org
|
Date:
| 24/06/2009 03:39
|
Subject:
| [sca-assembly-comment] Comments on Public
Review Draft 01 |
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.
<Editorial>
[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.
<Editorial>
[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.
<Issue 1>
[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.
<Issue 2>
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
<Issue 3>
[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).
<Issue 4>
The use of "services" (not in bold italic" and components
is confusing in this overview.
<Issue 5>
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
<Issue 6>
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)
<Issue 7>
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.
<Editorial>
"constrainingType" is misspelled on line 2314.
[6] Technical Section 7
<Issue 8>
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.
<Editorial - but a dup of an existing
issue that is already resolved>
Line 2401 has "Error! Reference source not found".
<Issue 9>
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.
<Issue 3 - this is the same as Issue 3
above, just referring to another part of the document>
The relationship to (e.g.) BPMN and BPEL may illuminate the choices and
the specification here.
[7] Technical Section 11 lines 3327ff
<Issue 10>
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.
<Editorial - but a dup of an existing
issue that is already resolved>
[8] Editorial line 2284
"Error! Reference not found"
[9] Conformance lines 3826ff
<Editorial> + <Praise>
!! ;-)
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
<Editorial>
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
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]