|Subject:||Re: [sca-bindings-comment] Comments on sca-jcabinding-1.1-spec.pdf|
|From:||Eric Johnson (er...@tibco.com)|
|Date:||Oct 8, 2009 8:59:36 am|
Your comment has been logged as: http://www.osoa.org/jira/browse/BINDINGS-99 for discussion by the TC.
Patrick Durusau wrote:
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)."
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."
The naming conventions for artifacts defined by this standard are:
a. SCA-Assembly (full cite)
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!
-- This publicly archived list offers a means to provide input to the OASIS Service Component Architecture / Bindings (SCA-Bindings) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
List help: sca-...@lists.oasis-open.org
List archive: http://lists.oasis-open.org/archives/sca-bindings-comment/
Feedback License: http://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sca-bindings Join OASIS: http://www.oasis-open.org/join/