sca-bindings message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Proposed response for issue BINDINGS-99
- From: Simon Holdsworth <simon_holdsworth@uk.ibm.com>
- To: sca-bindings@lists.oasis-open.org
- Date: Fri, 16 Oct 2009 12:27:29 +0100
Folks,
Here's my proposed response to the public
review comment that is the subject of issue BINDINGS-99.
> Greetings!
>
> Apologies for the late comments! Hope they prove to be helpful.
Thank you for your interest in the SCA Bindings specifications.
The TC welcomes your comments and has discussed them; 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.
The TC agrees that this needs to be checked.
An editorial action item has been created for the
editors to consider and address this
> 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 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 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.
> 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 an issue. 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 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 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 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 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 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 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.
> 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 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 and no change is proposed.
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]