[Issue 1] Java CAA - Issue 1 Proposal - new version uploaded

Simon,

Thanks for the review.  Comments
and responses inline in red

Updates are reflected in this new version
of the proposal:

http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/33042/sca-javacaa-1.1-spec-cd02-rev3%20Issue1%20rev%206.pdf

http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/33041/sca-javacaa-1.1-spec-cd02-rev3%20Issue1%20rev%206.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:  

From:
Simon Nash <>

To:
Mike Edwards/UK/IBM@IBMGB

Cc:


Date:
22/06/2009 22:14

Subject:
Re: [sca-j] Groups - Java CAA - Issue
1 Proposal - PDF (sca-javacaa-1.1-spec-cd02-rev3   Issue1 rev 5.pdf)
uploaded

Here are my comments on this draft.  Line numbers
are from the

PDF version.

  1. Line 1164: The type of the defaultFactoryFinder method should

     be the SPI interface SCAClientFactoryFinder, not the SCA-provided

     reference implementation class SCAClientFactoryFinderImpl.
 This

     allows vendors to inject their own implementations of the
SPI

     interface into this field.  This change also requires
deleting

     line 1160 and updating line 1181.

Agreed.  

  2. Lines 1234 - 1236: Replace this paragraph by the following text:

      Provides a means by which a provider of an SCAClientFactory

      implementation can inject a factory finder implementation
into

      the abstract SCAClientFactory class - once this is
done, future

      invocations of the SCAClientFactory use the injected
factory

      finder to locate and return an instance of a subclass
of

      SCAClientFactory.

Agreed.

  3. Line 1252: Change "implementation of the SCAClientFactory
interface"

     to "implementation of an SCAClientFactory subclass".

Done

  4. Line 1266: Change "SCARuntimeException" to "ServiceRuntimeException".

     This change also needs to be made in a number of other places
in

     the SCAClientFactoryFinderImpl code.

Done

  5. The duplication of code between sections 8.8 / 8.9 / 8.10 / 8.11

     and B.1.1 / B.1.2 / B.1.3 / B.1.4 needs to be resolved.
 There is

     currently about 95% overlap which is the worst of all possible
worlds.

     Having this code duplicated (with minor differences) in
different

     parts of the same specification document is redundant and
confusing,

     increases the maintenance burden, creates unnecessary opportunities

     for accidental inconsistency, and is not consistent with
what we do

     for the other API interfaces, classes and annotations.  It
also makes

     it hard to see the information at the start of sections
B.1.2, B.1.3

     and B.1.4 about about how vendors should use these APIs
and SPIs.

     I think the best approach is to document the normative APIs

     SCAClient, SCAClientFactory and SCAClientFactoryFinder only
in

     chapter 8, and the non-normative reference implementation

     SCAClientFactoryFinderImpl only in Appendix B.  This
may require

     a forward pointer from chapter 8 to Appendix B.

I take a different view.  I agree with
the point about duplication.

However, I liken this to the use of inline
pseudo-schemas and Appendixes with full XSDs.

I think this is useful in that the inline
schemas are deliberately shortened to allow concentration

on important points in the bulk of the text,
while having the full normative contents in the

appendix.  I will try to do the same
for the code.

This allows the main text to concentrate
on the normative and descriptive aspects while the

appendix contains all the detail but little
explanation.

  6. The code in appendix B has the same issues described in comments

     1 and 4 above.

Fixed

  7. Lines 2570: This incorrectly describes the SCAFactoryFinder class

     as a reference implementation.  Replace the first sentence
by:

     SCA provides an abstract base class SCAClientFactory.

Fixed

  8. Line 2571: Singular/plural confusion.  Replace the second
sentence

     of the paragraph by: Vendors can provide subclasses of this
class

     which create objects that implement...."

Fixed

  9. The comment text in lines 2597 - 2601 of Appendix B has the same

     issues described in comment 2 above.

Fixed

10. Section B.1.5 needs to be updated to be consistent with the recent

     changes to SCAClientFactoryFinder.  Specifically, option
3 of the

     second bullet needs to talk about injecting an instance
of the

     SCAClientFactoryFinder interface that implements the find()
method

     to return a vendor implementation instance of SCAClientFactory.

Done

   Simon

 wrote:

> The document revision named Java CAA - Issue 1 Proposal - PDF

> (sca-javacaa-1.1-spec-cd02-rev3 Issue1 rev 5.pdf) has been submitted
by Dr.

> Mike Edwards to the OASIS Service Component Architecture / J (SCA-J)
TC

> document repository.  This document is revision #1 of

> sca-javacaa-1.1-spec-cd02-rev3+Issue1.pdf.

> 

> Document Description:

> 

> 

> View Document Details:

> http://www.oasis-open.org/committees/document.php?document_id=33030

> 

> Download Document:  

> http://www.oasis-open.org/committees/download.php/33030/sca-javacaa-1.1-spec-cd02-rev3%20Issue1%20rev%205.pdf

> 

> Revision:

> This document is revision #1 of sca-javacaa-1.1-spec-cd02-rev3+Issue1.pdf.

> The document details page referenced above will show the complete
revision

> history.

> 

> 

> 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