[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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. 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. 3. Line 1252: Change "implementation of the SCAClientFactory interface" to "implementation of an SCAClientFactory subclass". 4. Line 1266: Change "SCARuntimeException" to "ServiceRuntimeException". This change also needs to be made in a number of other places in the SCAClientFactoryFinderImpl code. 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. 6. The code in appendix B has the same issues described in comments 1 and 4 above. 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. 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...." 9. The comment text in lines 2597 - 2601 of Appendix B has the same issues described in comment 2 above. 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. Simon mike_edwards@uk.ibm.com 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]