Re: [sca-bindings-comment] Comments on sca-jcabinding-1.1-spec.pdf

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

Patrick,

Thank you for your interest in the SCA Bindings specifications.
The TC welcomes your comments and has discussed them; as a result of your
comments we have opened two new issues and created 10 editorial actions.
Please refer to each comment for the TC's response.
 
> 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.

We have checked this with our legal team and believe that this is the correct
form.
 
> 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?> 

The TC agrees that clarification of this wording is required.
An editorial action item (20091015-4) has been created for the editors
to clarify the text describing the JCA binding
 
> 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. 

The TC agrees that this wording needs to either be improved or removed.
An editorial action item (20091015-5) has been created for the editors
to revise the text or remove it 

> 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. 

The TC agrees that improvements can be made here.
Issue BINDINGS-101 has been opened for the TC to discuss how to resolve
this. 
http://www.osoa.org/jira/browse/BINDINGS-101

> 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."

The TC agrees that this is a concern.  To a great extent changes have
been made by other SCA TC's to address this, so a similar approach will
be taken for the bindings specs. 
An editorial action item (20091015-6) has been created for the editors
to caption all examples, figures, snippets, etc., scrub text of use of
former, latter, above, below, following.  Replace with precise references.
 
> 6) Is there some reason to repeat the material from the abstract as
the 
> hanging paragraphs under #1?

The TC agrees that this could be improved. 
An editorial action item (20091015-7) has been created.
 
> 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.

The TC is comfortable with the current approach.

> 8) Non-Normative References? Still TBD?

An editorial action item (20091015-8) has been created to either populate
or remove this section. 
 
> 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.

An editorial action item (20091015-9) has been created to clean up the
naming conventions section. 
 
> 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. 

The TC agrees that this could be improved. 
An editorial action item (20091015-10) has been created to update wording
to clarify optionality. 

> 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.

An editorial action item (20091015-11) has been created to improve the
layout and wording in this case. 

> 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.)

The TC agreed that this is necessary. 
Issue BINDINGS-102 has been opened for the TC to discuss how to resolve
this. 
http://www.osoa.org/jira/browse/BINDINGS-102
 
> 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.

Given that this is introduced in Assembly for all bindings, the TC feels
it is valid in the JCA binding to state that no additional capability is
provided. 
 
> 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.

The TC feels that examples are important and useful to aid understanding.
 As per #5 examples will be captioned and correctly referenced. 

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

as #14 

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

The TC agreed that this is necessary. 
An editorial action item (20091015-12) has been created to indicate for
each annex whether it is normative or not. 
 
> 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?

The TC is comfortable with the wording of the conformance section, which
is consistent with the other SCA specifications and no change is proposed.


Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair
MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
Internet - Simon_Holdsworth@uk.ibm.com

---

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