Re: [sca-j] [ISSUE 1] Accessing SCA Services from non-SCA componentcode - Formal Proposal update

[Simon Nash <oasis@cjnash.com>]

Mike Edwards wrote:
> 
> Folks,
> 
> Here is a response to Simon's comments and an updated proposal document 
> for this afternoon.
> 
> http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31769/sca-javacaa-1.1-spec-cd02-rev3%20Issue1%20rev%203.pdf 
> 
> 
> 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: 	OASIS Java <sca-j@lists.oasis-open.org>
> Date: 	20/03/2009 09:59
> Subject: 	Re: [sca-j] [ISSUE 1] Accessing SCA Services from non-SCA 
> component code - Formal Proposal
> 
> 
> ------------------------------------------------------------------------
> 
> 
> 
> Mark,
> Here are my comments on the latest draft proposal document.
> I have not yet reviewed the code files.
> 
>  1. Lines 1139/1140 imply that the service name must always be
>     specified, even if there is only one service on the component.
>     Do we want to require this, or follow the assembly wiring
>     rules that allow the service name of be omitted in this case?
>     (I'm raising this for discussion, not proposing a change.)
> *<mje> Good question.  I don't have a strong view </mje>*
> 
As no-one feels strongly, let's leave it this way for now.

>  2. I not very comfortable with having section 8.9 define the methods
>     of SCAClientfactory using "..." notation.  The exact semantics of
>     these need to be part of the SCA standard.  Leaving these methods
>     as "..." might be OK if the method descriptions specified precise
>     semantics, but they don't.
> 
> *<mje> I view this as similar in nature to the pseudo-schemas of the 
> Assembly spec and*
> *I think it is good.*
> *The "exact semantics" are NOT part of the normative part of the spec, 
> since an*
> *provider can choose to vary them.  The only things that are guaranteed 
> are those*
> *stated in this section.  Any further semantics must be defined by the 
> provider - and*
> *for the default, it is defined in the appendix of this spec*
> *</mje>*
> 
As we discussed on Friday's call, it's OK to have a summary here
and put additional normative detail in the appendix, as we do for
pseudo-schemas.

Some of the semantics of this class need to be a normative part
of the spec.  Specifically, this class MUST support injection
of a factory into the defaultFactory injection point and use the
injected factory if one is present, and the various newInstance()
methods MUST result in a call to createSCAClient() on the vendor
factory.  This could be stated either in the chapter 8 or in the
appendix, but it needs to be stated normatively somewhere.

>  3. Why are there two definitions for the SCAClient interface, one
>     in section 8.8 and one in section B.1.1?  These should be merged
>     into one place (section 8.8) as we do for all the other interfaces.
> *<mje>*
> *I take the opposite view and think that all the code provided as part 
> of this specification*
> *should be ALSO listed in the appendix as well as the definitional 
> material in the body of*
> *the document.  I think the appendix should be a copy of the actual code 
> artifacts,*
> *comments and all.*
> 
We don't do this for any of the other interfaces or annotation
definitions.  Given that we are shipping a zip file containing all
the code, it would not make sense to copy every line of this zip file
into to the specification as well.  I believe the resolution to
JAVA-121 established the correct split between what goes in the
spec and what goes in the zip file.  The SCAClient interface is no
different in this respect from any other interface in Chapter 8
or annotation in chapter 9 and should not be treated differently.

>  4. Same comment for SCAClientFactory.  In this case there is slightly
>     more justification for the separation because this is a class.
>     If we are going to do this split, section 8.9 needs to point to section
>     B.1.2 and state that section B.1.2 is a normative part of the standard.
> *<mje> Well, its the signature that is normative, in the sense that a 
> provider could*
> *replace the behaviour completely - this is a point to discuss*
> *</mje>*
> 
There is a normative mechanism provided in the code for a vendor to
replace the factory finder reference implementation using injection
of the defaultFactory.  However, this does not replace the code in
this class.  Specifically, the defaultFactory injection point MUST
be supported and the newInstance() methods MUST result in a
createSCAClient() call to the vendor factory.  This is necessary
to allow vendor A's SCAClientFactory class to be used with vendor B's
factory implementation.

Having thought some more about how this A/B scenario will work in
practice, I'm not sure that we have the vendor extension point right
at the moment.  Injecting into defaultFactory currently short-circuits
the factory finding process and causes all arguments passed to the
newInstance() method to be ignored.  This means that if vendor A uses
this injection point, there is no capability for vendor B's factory
to be located or used, even if suitable properties and/or class loader
objects were passed to newInstance().

An alternative approach is for the injection point to not be the
factory itself, but the factory finder.  This would allow vendors to
replace the SCA reference implementation of the factory finder with
their own implementation.  This implementation would be able to
either use or ignore the arguments passed to newInstance().  We could
have an abstract normative base class for SCAClientFactoryFinder that
works in a similar way to the abstract base class for SCAClientFactory,
with SCA providing a non-normative factory finder reference
implementation that is a concrete subclass of SCAClientFactoryFinder.
A vendor could implement their own subclass of SCAClientFactoryFinder
and inject an instance of this subclass into a protected field of
SCAClientFactory called defaultFactoryFinder.  If a vendor does this,
the default reference implementation would not be used and would not
need to be present.  I'll send a separate email with details of how
the code for this would look.

>  5. On line 2355, the package should be ".impl" not ".spi".
> *<mje>Fixed</mje>*
> 
>  6. The title of section B.1.3 should be SCAClientFactoryFinder.
> *<mje>Fixed</mje>*
>  7. In line 2443, change SCAClientFactory to SCAClientFactoryFinder.
> *<mje>Fixed</mje>*
>  8. The bulleted list in lines 2445-2448 should be numbered, and
>     the preceding text should say that the lookup follows this order.
> *<mje>Fixed</mje>*
>  9. On line 2454, the package should be ".impl" not ".spi".
> *<mje>Fixed</mje>*
> 10. I don't think it's useful for the reference implementation code to
>     be part of Appendix B.  This isn't a normative part of the
>     standard and should be provided in the zip file.
> *<mje>I disagree - this material IS part of the material produced by the 
> TC</mje>*
 >
The zip file is also part of the material produced by the TC.  For
non-normative code in this zip file, I don't see the value in also
copying this code into the spec.  However, if we are going to include
this code in the spec, we should separate it into a separate appendix
from any normative code and clearly mark this appendix as non-normative.

> 11. Comment in lines 2468-2470 is wrong.
> *<mje>Fixed</mje>*
> 12. Comment in lines 2499-2501 is wrong.
> *<mje>Fixed</mje>*
> 13. In line 2504, change SCAClient to SCAClientFactory.
> *<mje>Fixed</mje>*
> 14. In line 2506, change SCAClient to SCAClientFactory.
> *<mje>Fixed</mje>*
> 15. In line 2507, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 16. In line 2508, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 17. In line 2542, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 18. In line 2544, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 19. In line 2562, change checkMETAINFServicesForSIPClassName to
>     checkMETAINFServicesForSPIClassName.
> *<mje>Fixed by changing to *checkMETAINFServicesForClassName*</mje>*
> 20. In line 2572, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 21. In line 2575, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 22. In line 2594, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 23. In line 2597, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 24. In line 2600, change checkMETAINFServicesForSIPClassName to
>     checkMETAINFServicesForSPIClassName.
> *<mje>Fixed</mje>*
> 25. In line 2688, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 26. In line 2691, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 27. In line 2693, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 28. In line 2695, change SCAClientFactorySPI to SCAClientFactory.
> *<mje>Fixed</mje>*
> 29. Section B.1.4 should not be in the appendix.  It needs to be
>     moved into the main body of the spec with appropriate normative
>     language.
> *<mje>I disagree - there is nothing normative we can say about 
> vendors</mje>*
 >
OK, I agree with this.  If we add appropriate normative language
for how SCAClientFactory works, that would cover it.

   Simon

>   Simon
> 
> Mike Edwards wrote:
>  >
>  > Mark,
>  >
>  > Looks fine to me, thanks for the update.
>  >
>  > 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:                  "Mark Combellack" <mcombellack@avaya.com>
>  > To:                  <sca-j@lists.oasis-open.org>, "David Booz" 
> <booz@us.ibm.com>, Mike
>  > Edwards/UK/IBM@IBMGB
>  > Date:                  19/03/2009 15:01
>  > Subject:                  RE: [sca-j] [ISSUE 1] Accessing SCA 
> Services from non-SCA
>  > component code - Formal Proposal
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  >
>  >
>  > Hi,
>  >  
>  > Thanks Mike for putting all the pieces of this proposal together.
>  >  
>  > I’ve updated the text of the proposal to incorporate feedback from Dave
>  > and other earlier comments on the mailing list. The changes I have made
>  > are:
>  >  
>  >
>  >     * Corrected the import statements in the sample code in section 4.2.1
>  >     * Delete text at end of section 8.1 which talked about non-SCA
>  >       Clients using the ComponentContext to look up services
>  >     * Changed private defaultFactory to protected in section 8.9
>  >     * Changed private defaultFactory to protected in Appendix B.1.2
>  >     * Trimmed the implementation code out of the SCAClientFactory in
>  >       section 8.9
>  >     * Changed SCA domain to SCA Domain in the modified text to be
>  >       consistent with the rest of the specification
>  >     * Delete paragraph saying vendors are free to replace
>  >       SCAFactoryFinder with their own version
>  >     * Deleted option 4 in Appendix B.1.4
>  >
>  >  
>  > It should be noted that I have not addressed two of Dave’s issues. These
>  > are the last bit of point 2 and point 3
>  >  
>  > I have created a new revision 2 of this proposal which can be found at:
>  >  
>  > Proposal (PDF):
>  > 
> _http://www.oasis-open.org/committees/download.php/31746/sca-javacaa-1.1-spec-cd02-rev3%20Issue1%20rev%202.pdf_ 
> 
>  >
>  > Proposal (Word):
>  > 
> _http://www.oasis-open.org/committees/download.php/31745/sca-javacaa-1.1-spec-cd02-rev3%20Issue1%20rev%202.doc_ 
> 
>  >
>  >  
>  > Thanks,
>  >  
>  > Mark
>  > Mark Combellack| Software Developer| Avaya | Eastern Business Park | St.
>  > Mellons | Cardiff | CF3 5EA | Voice: +44 (0) 29 2081 7624 |
>  > _mcombellack@avaya.com_ <mailto:|mcombellack@avaya.com>
>  >
>  > ------------------------------------------------------------------------
>  >
>  > *From:* David Booz [mailto:booz@us.ibm.com] *
>  > Sent:* 18 March 2009 17:20*
>  > To:* sca-j@lists.oasis-open.org*
>  > Subject:* Re: [sca-j] [ISSUE 1] Accessing SCA Services from non-SCA
>  > component code - Formal Proposal
>  >  
>  >
>  > All line numbers are from the pdf.
>  >
>  > 1) delete works for me
>  >
>  > */[Mark Combellack] Deleted this text/*
>  >
>  > 2) I don't feel strongly about the full source being in an appendix, if
>  > there's a good reason, I am ok with it. My point on #2 was focused on
>  > the FactoryFinder, and esp. in that it appears on line 1179. Option4 in
>  > B.1.4 is not an option for vendors, we removed that in the last call.
>  >
>  > */[Mark Combellack] Deleted option 4/*
>  >
>  > And further, I don't think any of the implementation of those
>  > SCAClientFactory methods should appear in the body of the spec (near
>  > line 1179). Appendix is fine.
>  > Concretely I think you should remove lines 1164, 1168, 1172, 1176-1185,
>  > and lines 2776-2779.
>  >
>  > */[Mark Combellack] Deleted implementation code in the text in the lines
>  > specified./*
>  >
>  > If we have to publish in the spec, all the classes that are part of the
>  > OASIS ref impl, then I think we should also consider merging the factory
>  > finder into the OASIS SCAClientFactory since it's no longer an SPI (and
>  > then we can remove B.1.3 entirely).
>  >
>  > */[Mark Combellack] I have not addressed this issue/*
>  >
>  >
>  > 3) The point here was the info in B.1.4, line 2745 is actually part of
>  > the end user programming model (option1 and option2), and thus I think
>  > it should appear in the body of the spec somewhere near or in 8.9.
>  >
>  > */[Mark Combellack] I have not addressed this issue/*
>  >
>  >
>  >
>  > Dave Booz
>  > STSM, BPM and SCA Architecture
>  > Co-Chair OASIS SCA-Policy TC and SCA-J TC
>  > "Distributed objects first, then world hunger"
>  > Poughkeepsie, NY (845)-435-6093 or 8-295-6093
>  > e-mail:booz@us.ibm.com
>  >
>  > Inactive hide details for Mike Edwards ---03/18/2009 10:19:16 AM---Dave,
>  > In response:Mike Edwards ---03/18/2009 10:19:16 AM---Dave, In response:
>  >
>  >
>  > From:                  
>  > Mike Edwards <mike_edwards@uk.ibm.com>
>  >
>  > To:                  
>  > sca-j@lists.oasis-open.org
>  >
>  > Date:                  
>  > 03/18/2009 10:19 AM
>  >
>  > Subject:                  
>  > Re: [sca-j] [ISSUE 1] Accessing SCA Services from non-SCA component code
>  > - Formal Proposal
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  >
>  >
>  >
>  >
>  > Dave,
>  >
>  > In response:
>  >
>  > 1) I simply missed it. I propose that we remove the final paragraph of
>  > section 8.1.
>  >
>  > 2) I think there is a problem here - we are defining code that WILL be
>  > published as artifacts of the OASIS SCA-J TC
>  > If they are not published in the spec, what standing do they have?
>  >
>  > Personally, I see no problem in publishing the code in full in the
>  > Appendix.. Their standing is then very clear.
>  > The fact that the implementation is there for all to see is not a
>  > problem in my opinion.
>  >
>  > 3) I chose the appendix for the information for the providers since this
>  > is a very different level of material from a description of
>  > APIs, which is what the main part of the spec is supposed to be (from
>  > its very title!!). I suppose this material could be placed into
>  > some new section in the body of the spec, which would have to be given a
>  > title like SCAClient SPI, but I don't feel very
>  > enthusiastic about doing it that way.
>  >
>  > I'm not sure how much of this information is useful to end users.
>  > Perhaps if you could point it out in detail, we could agree
>  > to include that in the main text. The problem I see is that for a given
>  > provider, the user information is likely to be unique to
>  > that provider.
>  >
>  > 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:                  David Booz <booz@us.ibm.com>
>  > To:                  sca-j@lists.oasis-open.org
>  > Date:                  18/03/2009 13:46
>  > Subject:                  Re: [sca-j] [ISSUE 1] Accessing SCA 
> Services from non-SCA
>  > component code - Formal Proposal
>  >
>  >
>  >  
>  >
>  > ------------------------------------------------------------------------
>  >
>  >
>  >
>  >
>  > Thanks for writing this up. It's a really good start. Just a couple of
>  > comments:
>  >
>  > 1) I was surprised that you didn't address your Word comment at the end
>  > of section 8.1
>  >
>  > 2) I don't think we want to expose the implementation of the
>  > SCAClientFactory methods in the spec....esp. the FactoryFinder usage. I
>  > think we do need to expose the defaultFactory attribute as that is the
>  > injection point for vendors. Further, section B.1.3 goes into detail
>  > about FactoryFinder being overridden, but I thought we agreed on the
>  > last call that factory finder had become an implementation detail of the
>  > OASIS SCAClientFactory. Vendors will replace SCAClientFactory (possibly
>  > through injection) and therefore the finder factory becomes moot. This
>  > comment ripples into B.1.4 also.
>  >
>  > 3) There's good info at the start of B.1.3 and in B.1.4 about what
>  > vendors have to do, including the text about how to override the
>  > SCAClientFactory class. Is an appendix really the right place for that?
>  > It's always difficult to balance writing the specs for vendors vs the
>  > vendor's users/customers. Seems that some of this is very important for
>  > users to know.
>  >
>  >
>  >
>  > Dave Booz
>  > STSM, BPM and SCA Architecture
>  > Co-Chair OASIS SCA-Policy TC and SCA-J TC
>  > "Distributed objects first, then world hunger"
>  > Poughkeepsie, NY (845)-435-6093 or 8-295-6093
>  > e-mail:booz@us.ibm.com
>  >
>  > Inactive hide details for Mike Edwards ---03/17/2009 10:20:04
>  > AM---Folks, I have created a formal proposal for Issue 1 based onMike
>  > Edwards ---03/17/2009 10:20:04 AM---Folks, I have created a formal
>  > proposal for Issue 1 based on CD02 Rev3 and on
>  >
>  >
>  > From:                  
>  > Mike Edwards <mike_edwards@uk.ibm.com>
>  >
>  > To:                  
>  > "OASIS Java" <sca-j@lists.oasis-open.org>
>  >
>  > Date:                  
>  > 03/17/2009 10:20 AM
>  >
>  > Subject:                  
>  > [sca-j] [ISSUE 1] Accessing SCA Services from non-SCA component code -
>  > Formal Proposal
>  >
>  >
>  >  
>  >
>  > ------------------------------------------------------------------------
>  >
>  >
>  >
>  >
>  >
>  > Folks,
>  >
>  > I have created a formal proposal for Issue 1 based on CD02 Rev3 and on
>  > Mark's latest email: _
>  > __
>  > 
> __http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31702/sca-javacaa-1.1-spec-cd02-rev3%2BIssue1.pdf_ 
> 
>  > _
>  > 
> __http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31701/sca-javacaa-1.1-spec-cd02-rev3%2BIssue1.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
>  >
>  > ------------------------------------------------------------------------
>  >
>  > /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/
>  >
>  >  
>  >
>  >
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  >  
>  >
>  > /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/
>  >
>  >
>  >
>  >
>  >
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  > /
>  > /
>  >
>  > /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/
> 
> 
> 
> 
> 
>