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] Fw: [sca-assembly-comment] Comments on Public ReviewDraft 01


+1

Dave Booz
STSM, BPM and SCA Architecture
Co-Chair OASIS SCA-Policy TC and SCA-J TC
"Distributed objects first, then world hunger"
Poughkeepsie, NY (845)-435-6093 or 8-295-6093
e-mail:booz@us.ibm.com

Inactive hide details for Mike Edwards ---06/24/2009 04:13:17 AM---Folks, I have marked up the following set of comments on theMike Edwards ---06/24/2009 04:13:17 AM---Folks, I have marked up the following set of comments on the Assembly spec as


From:

Mike Edwards <mike_edwards@uk.ibm.com>

To:

"OASIS Assembly" <sca-assembly@lists.oasis-open.org>

Date:

06/24/2009 04:13 AM

Subject:

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






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]