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

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

Eric, 

My opinion is that we should open a
single issue for each comment email.  Once that's open we can discuss
how to respond to the email overall, and as part of that response we may
choose to open additional issues to cover each comment that may require
a spec change.  The original issue will then be closed when we agree
on the content of the response to the sender of the comment.

Regards, Simon

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

From:	Eric Johnson <eric@tibco.com>
To:	OASIS SCA Bindings <sca-bindings@lists.oasis-open.org>
Date:	07/10/2009 18:10
Subject:	[sca-bindings] [Fwd: [sca-bindings-comment] Comments on sca-jcabinding-1.1-spec.pdf]

---

Is it the desire of the TC that I enter each numbered
item as a separate issue in JIRA?

-Eric.

-------- Original Message --------

Subject:	[sca-bindings-comment] Comments on sca-jcabinding-1.1-spec.pdf
Date:	Wed, 07 Oct 2009 10:57:04 -0400
From:	Patrick Durusau <patrick@durusau.net>
To:	sca-bindings-comment@lists.oasis-open.org

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

-- 
Patrick Durusau
patrick@durusau.net
Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps) 


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

Subscribe: sca-bindings-comment-subscribe@lists.oasis-open.org
Unsubscribe: sca-bindings-comment-unsubscribe@lists.oasis-open.org
List help: sca-bindings-comment-help@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
Committee: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sca-bindings
Join OASIS: http://www.oasis-open.org/join/


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates
this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

---

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