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

[Eric Johnson <eric@tibco.com>]

Hi Patrick,

Your comment has been logged as:
http://www.osoa.org/jira/browse/BINDINGS-99 for discussion by the TC.

-Eric.

Patrick Durusau wrote:
> 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
>