Comments on sca-jcabinding-1.1-spec.pdf

[Patrick Durusau <patrick@durusau.net>]

Greetings!

Apologies for the late comments! Hope they prove to be helpful.

1) Need to check with Jamie Clark but the copyright "2007, 2009" looks 
odd. Usual case is 2007-2009 (or whatever are the correct years). Since 
the TC started in 2007 no one would quarrel with the start date but why 
skip 2008? Not sure it is a problem but do need to check.

2) Not sure about: "This document presents a binding describing access 
and connectivity to the services provided by Enterprise Information 
Systems (EIS)."

Does the binding describe the access and connectivity or does the 
standard/document describe the binding that enables access and 
connectivity?

Thus: "This document describes a binding that facilitates access and 
connectivity to the services provided by Enterprise Information Systems 
(EIS)."

Yes?

3) Since further specifications aren't defined here, I would lose:
> Further specification is necessary to define EIS Bindings between 
> different SCA runtimes within SCA system, for example J2EE and EIS 
> based runtimes.
4) Need to check the draft for opaque references, like "the composite's 
references and services." I have no idea at this point what a composite 
may or may not be. (Ah, is a composite the SCA Composite Document of 7.1?

I am not a big fan of definition lists, with out of context definitions 
but it could be helpful to define terms like "composite" in prose the 
first time they are used.
> The JCA Bindings are applicable to the composite’s references and 
> services.
5) As a general rule, don't use former/latter, above/below, following, 
etc. as such references can be ambiguous.

> The connection to exchange data with the EIS is characterized by two 
> sets of configuration parameters, the connection and interaction 
> parameters. The former set determines the location of the target 
> system the latter determines characteristics that need to be specified 
> to invoke one specific service available at the endpoint.
Thus: "Configuration parameters specify the location of a target system 
and interaction parameters specify what is required to invoke one 
specific service available at an endpoint."

Do note the target -> a target.

Recall that you are writing a standard for the general case and not a 
binding for some resource in particular, which would be referred to as 
"the target."

6) Is there some reason to repeat the material from the abstract as the 
hanging paragraphs under #1?

7) Do note that hanging paragraphs are to be discouraged. The paragraphs 
under 1 Introduction are "hanging paragraphs.) To illustrate, if I say 
See 1 Introduction, do I mean the five paragraphs following 1 
Introduction or do I mean that *plus* 1.1 - 1.4 inclusive? Can't tell if 
all I say is see 1 Introduction.

8) Non-Normative References? Still TBD?

9) 1.4 Naming Conventions. This is pretty important and so I would 
tighten it up.

"This specification follows some naming conventions for artifacts 
defined by the specification."

Say rather:

The naming conventions for artifacts defined by this standard are:

a. SCA-Assembly (full cite)

b.

c. , etc.

And just state each one. The "some naming conventions" sounds weak. 
Consider using the ISO "shall" terminology in re-casting the 
definitions, lose the examples.

10) General comment: Review the text for statements like:

"the binding’s @uri attribute allows for the specification of the 
endpoint."

Rather: "The binding's @uri attribute specifies an endpoint."

Specification announce the standard. No need to be timid about doing so.

11) Ah, I take it that @uri has different meanings depending on context. 
Just a suggestion but I would break those out into separate sections. 
Admittedly takes more room (I did that in ODF 1.2) but it does make it 
clear what context the attribute has for a particular meaning.

12) Just skipping ahead a bit:

"/binding.jca/inboundConnection/activationSpec/@create attribute 
indicates whether the element containing the attribute should be created 
when the containing composite is deployed. Valid values are “always”, 
“never” and “ifNotExist”."

I would enumerate and *define* every valid attribute value. Even for 
booleans. Just a good practice. I am sure the meaning of the values are 
"obvious" to TC members but that's not the test. (Believe me, I know 
what a chore this is.)

13) I would drop 4 Operation Selectors and Wire Formats. Good to say 
what the standard doesn't define but usually that is done, briefly, in 
the abstract or what would be called scope in ISO.

14) 5 Binding Properties - Just a preference on my part but I would lose 
the example material. Very legitimate and very useful, but in my view 
somewhere other than the standard. Has the benefit of making the 
standard shorter, tighter.

15) In light of #14 you know how I feel about Section 6. ;-)

16) I can guess but each annex needs to be labeled normative (like B I 
assume) or non-normative (like the list of participants).

17) Where it says: "The implementation MUST comply with all statements 
in Appendix B: “Conformance Items” related to an SCA Runtime, notably 
all "MUST" statements have to be implemented"

Err, I think the first "MUST" here is confusing. I suspect what was 
meant was that the implementation conforms to the conformance items 
specified in Annex B. That is to say, let Annex B states its musts, 
etc., for itself. Yes?

Apologies for not being more complete but I tried to hit the high points 
that would produce the most clarity.

Hope everyone is having a great week!

Patrick

-- 
Patrick Durusau
patrick@durusau.net
Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)