[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-bindings-comment] Comments on sca-jcabinding-1.1-spec.pdf
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 >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]