[ISSUE 105] RFC2119 Language is needed for C&I Specification - responses tocomments and updated draft

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

Simon,

Responses inline...

New proposal draft:

http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31694/sca-javaci-1.1-spec-wd04_proposal2.pdf
http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31693/sca-javaci-1.1-spec-wd04_proposal2.doc

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:	Simon Nash <oasis@cjnash.com>
To:	sca-j@lists.oasis-open.org
Date:	05/03/2009 20:37
Subject:	Re: [sca-j] Groups - SCA Java C&I WD04 proposal (PDF)   (sca-javaci-1.1-spec-wd04_proposal.pdf) uploaded

---

Mike,
Here my comments from a complete review of the document.  I have not
repeated the comments that I made on Monday's call, except for the
final one about the implementation.java schema to remind us that an
issue is needed for this.  Line numbers are taken from the PDF document.
I have indicated those comments for which I think issues are needed.

  1. Page 1 (front cover): replace "supercedes" by "supersedes".
<mje>Fixed - although disputed</mje>

  2. Line 20: Refer to latest version of Assembly spec.
<mje>It is the latest public version
- have to wait for CD03 to be public</mje>

  3. Line 23: Refer to latest version of JavaCAA spec.
<mje>Ditto</mje>

  4. Line 36: Non-normative "may".
<mje>Fixed</mje>

  5. Lines 47-48: Contradiction with lines 143-144.  Here it
says that
     an SCA interface defined by a Java class is not remotable.
     In lines 143-144 it says that implementation classes can
be
     marked with @Remotable.  We need to decide which is
correct.
     [ISSUE NEEDED]
<mje>OK -leaving this for the issue</mje>

  6. Line 49: Add reference [JAVACAA].
<mje>Fixed</mje>

  7. Line 90: The "can also define" suggests that @Service
could specify
     both an interface and the implementation class.  The
"as opposed to"
     that precedes it suggests that it's one or the other.  The
spec needs
     to be clear on whether or not this should be allowed. [ISSUE
NEEDED]
<mje>Not sure of your point
here - should be clearer when you raise the issue</mje>
  8. Lines 109 and 132: Namespace appears in wrong font.
<mje>Fixed</mje>
  9. Lines 112, 135 and 138: "interface" should not be in
bold font, as
     this isn't Java code.
<mje>Fixed</mje>
10. Lines 143-144: See comment 5 above.
<mje>ok</mje>
11. Lines 156-158 and 166-168: Almost an exact repetition.  I suggest
     removing the 166-168 version as the 156-158 version is more
complete.
<mje>Fixed - although not in the way
suggested</mje>

12. Line 191: Two spaces after the "=" sign.
<mje>Fixed</mje>
13. Lines 195, 200, 233, 236 and 343: remove "public or protected".
<mje>Fixed</mje>
14. Line 203 (also 235 and 238): Should say that injection always occurs
     before the first service method is called (as in the previous
paragraph).
<mje>Fixed</mje>
15. Line 207 and 241: Non-normative "optional".
<mje>Fixed</mje>
16. Lines 209-210: Replace "references can also be determined"
by
     "references are determined".  Similar change
needed in 243-244.
<mje>Fixed</mje>
17. Line 220: Typo "propertoes".  Are these good to eat?
:-)
<mje>Fixed - my toes are very
proper, thank you</mje>
18. Line 229: Space after the dot.
<mje>Fixed</mje>
19. Line 259: What does the "unambiguously" mean?  Just
that every parameter
     must be marked with either @Property or @Reference?  If
so, there is
     a potential problem.  What if there are two constructors
that both
     have all of their parameters marked with either @Property
or @Reference?
     The two constructors could have the same property/reference
names or
     different property/reference names.  In both cases,
this would be an
     error.  I think the best way to handle this is to add
words in the
     JavaCAA spec to outlaw these illegal combinations.  It
would also be
     helpful to clarify the meaning of "unambiguously"
here. [ISSUE NEEDED]
<mje>OK, an issue is needed
here I think.  "Unambiguously" to me requires that each
and
every parameter not only has either a @Reference
or a @Property annotation but also that
the annotations declare a name.

The case of 2 constructors meeting the requirements
listed needs to be dealt with - both
for the @Constructor annotation and for the
constructors with all parameters annotated.
It is illegal for there to be more than 1
constructor that meets these criteria.  There is
an implied ordering I think - ie @Construtor
annotated constructor first, then a
constructor with all parameters annotated
then a no-arg constructor.  I think the issue may
need to make changes to this C&I spec
as well as the CAA spec.</mje>

20. Lines 265-269.  There has been some discussion on the email list
about
     this.  It needs fixing.  See my comments in
     http://www.oasis-open.org/apps/org/workgroup/sca-j/email/archives/200902/msg00243.html
<mje>I've left this - needs
an issue</mje>
21. Lines 345-346: Text reads "...API methods....methods...".
 Remove the
     second "methods" on line 346.
<mje>Fixed</mje>
22. Lines 489, 499, 508, 517: When this issue was resolved, we agreed to
     add an editorial comment pointing out the lower case "s"
in the second
     method name.  This wasn't done when the issue resolution
was applied.
<mje>Fixed - I commented every
method</mje>
23. Line 643: Delete conformance statement JCI00005, because this is
     already covered by JCI00001.
<mje>Fixed</mje>
24. Line 644: Delete conformance statement JCI00006, because this is
     already covered by JCI00004.
<mje>Fixed</mje>
25. Line 678: Change "composite" to "contribution".
<mje>Fixed</mje>
26. Appendix A: Add schema for implementation.java and refer to it in
     the Conformance section. [ISSUE NEEDED]
<mje>OK</mje>
   Simon

mike_edwards@uk.ibm.com wrote:
> The document named SCA Java C&I WD04 proposal (PDF)
> (sca-javaci-1.1-spec-wd04_proposal.pdf) has been submitted by Dr.
Mike
> Edwards to the OASIS Service Component Architecture / J (SCA-J) TC
document
> repository.
> 
> Document Description:
> 
> 
> View Document Details:
> http://www.oasis-open.org/committees/document.php?document_id=31463
> 
> Download Document:  
> http://www.oasis-open.org/committees/download.php/31463/sca-javaci-1.1-spec-wd04_proposal.pdf
> 
> 
> PLEASE NOTE:  If the above links do not work for you, your email
application
> may be breaking the link into two pieces.  You may be able to
copy and paste
> the entire link address into the address field of your web browser.
> 
> -OASIS Open Administration



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