Re: [sca-bindings] Document with proposed resolutions to JCA issues 120, 121, 122, 123

[Mike Edwards <mike_edwards@uk.ibm.com>]

Folks,

Comments inline:

Yours,  Mike.

Strategist - Emerging Technologies, SCA & SDO.
Co Chair OASIS SCA Assembly TC.
IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  
Email:  mike_edwards@uk.ibm.com

From:	Eric Johnson <eric@tibco.com>
To:	Simon Holdsworth/UK/IBM@IBMGB
Cc:	sca-bindings@lists.oasis-open.org
Date:	11/03/2010 02:30
Subject:	Re: [sca-bindings] Document with proposed resolutions to JCA issues 120, 121, 122, 123

---

Hi Simon,

<mje>
General comment (applies
to all that follows).

I much prefer normative
statements to state what must be the case for things to be correct than
to say "if x isn't true then raise an error".
There is a general
catch-all about error raising in the Assembly spec that deals with what
an SCA runtime must do when it encounters
some problem, so in
my view, there is no need to write a lot of normative statements that say
anything about raising errors.

Bottom line:  Write
normative statements that say positively what must be true
</mje>

Editorial nit - in at least one place you appear to have deleted the word
"element" at the start of a description.  This construction
appears in other places, and it probably should be consistent.

Hmm: BJC 20021 currently reads:
"For an SCA service with a binding.jca element with the @uri attribute
value specified, if the resource is not present at the JNDI location identified
by the @uri attribute or is not an Activation Spec the SCA runtime MUST
raise an error"

If I'm interpreting this correctly, Demorgan's
law suggests a rewrite: (!present || !activation
spec) is equivalent to !(present && activation spec)

I think this is saying that the JNDI location must identify a resource,
and that resource must be an Activation Spec.  I'd reword this as:
"For an SCA service with a binding.jca element with the @uri attribute
value specified, if the JNDI location identified by the @uri attribute
does not locate an Activation Spec, the SCA runtime MUST raise an error."

<mje>
"For an SCA service
with a binding.jca element with a @uri attribute value specified, the @uri
attribute value MUST identify a JNDI location containing an Activation
Spec"
</mje>

Likewise for BJC 20022, which reads:
"For an SCA reference with a binding.jca element with the @uri attribute
value specified, if the resource is not present at the JNDI location identified
by the @uri attribute or is not a Connection Factory the SCA runtime MUST
raise an error"

I'd change this to:
"For an SCA reference with a binding.jca element with the @uri attribute
value specified, if the JNDI location identified by the @uri attribute
does not locate a Connection Factory, the SCA runtime MUST raise an error

<mje>
"For an SCA reference
with a binding.jca element with a @uri attribute value specified, the @uri
attribute value MUST identify a JNDI location containing a Connection Factory"
</mje>

Feels to me like the normative statements for BJC20026 & BJC20027 could
(should?) be combined into one.  Instead of:
"The value of the outboundInteraction/operation/@name attribute MUST
be unique within the ouboundInteraction element" and "The value
of the outboundInteraction/operation/@name attribute MUST match the name
of one of the operations in the containing service's or reference’s interface"

why not:
"For the value of the outboundInteraction/operation/@name attribute,
if the value matches any other operation/@name attribute value under the
same outboundInteraction element, or if the value does not correspond to
the name of one of the operations in the interface for the containing service
or reference, the SCA runtime MUST raise an error."

<mje>
"The value of
an outboundInteraction/operation/@name attribute MUST correspond to the
name of one of the operations in the interface of the containing service
or reference and MUST NOT be the same as the value of any other operation/@name
attribute of the same outboundInteraction element"
</mje>
<mje>
I have a small preference
for separating the MUST and the MUST NOT statements here.  The reason
is that it makes writing the Test Assertions easier.  There are clearly
2 different test assertions and it is simpler in my opinion to be able
to associate each one with a unique normative statement.:

"The value of
an outboundInteraction/operation/@name attribute MUST correspond to the
name of one of the operations in the interface of the containing service
or reference"
"The value of
an outboundInteraction/operation/@name attribute MUST NOT be the same as
the value of any other operation/@name attribute of the same outboundInteraction
element"
</mje>

BJC20029 is appearing before the @type attribute, rather than after.

This is unrelated to Simon's changes: Is it just me, or does the normative
statement JBC20016 not make sense?  It says if something does not
exist, it must be interpreted as implementing MessageListener.  How
can something that doesn't exist implement anything?

<mje>
"not existing"
here sounds like "the default value for this attribute is..."
We use defaults all
the time - it might be better to use that terminology:

"If the inboundInteraction/listener
element is not specified, the SCA runtime MUST use as a default a listener
implementing the javax.resource.cci.MessageListener interface from the
JCA specification"
</mje>


BJC20023 says: "The value of the inboundInteraction/inboundOperation/@name
attribute MUST match the name of one of the operations in the containing
service's or reference's interface".  Don't we want this to read:

<mje>
No, for the reason
I gave at the start
- the formulation above
is the same as the form I propose for the outboundInteraction/operation/@name
above...

so I can at least claim
to be consistent  ;-)
</mje>

"If the value of the inboundInteraction/inboundOperation/@name does
not match the name of one of the operations in the interface from the containing
service or reference, then the SCA runtime MUST raise an error."

-Eric.

On 03/10/2010 09:13 AM, Simon Holdsworth wrote: 

Folks, 

In the interest of getting these issues closed as quickly as possible,
I've produced an updated revision of the JCA binding spec that includes
the proposed resolutions for these issues. 

I did modify some of the specific resolution text from what's in JIRA,
and also made some other minor changes around the normative statements
which were not originally stated, so the changes in this document constitute
the current proposed resolution for each of these issues.

I hope putting them all in one document does not confuse matters, I couldn't
face making four separate documents. 



Here's a PDF version, unfortunately again my PDF writer has chosen to mark
a load of cross references as having been updated when there is actually
no change to the text.  I have not changed any normative statements
from BJC20001 to BJC20020; everything from BJC20021 onwards is new.



Regards, Simon 

Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair,
AT&T and Boeing Lab Advocate
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

---

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

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