Re: [sca-j] JAVA-1: Source code for SCAClientFactory proposal - somethoughts

[Simon Nash <oasis@cjnash.com>]

Mike,
Thanks for the clarification.  Mark and I have been having some
offline discussions about a similar approach that keeps SCAClient
as an interface and has the same effect of allowing an implementation
provider to replace the code that creates the domain-specific
implementation of SCAClient.

I was waiting for Mark to post something, but I am now wondering
if he is waiting for me to post something.

This may be my last opportunity to post anything for a while, so
I'll sketch out our thoughts here.

Taking Mark's proposal as a starting point...

Instead of mandating a specific implementation of SCAClientFactory,
we would state in the specifications that vendors MUST implement
SCAClientFactory to look up a vendor-specific factory according to
a set of normative rules that we lay down in the specification.

In addition, OASIS would distribute a non-normative "reference
implementation" of SCAClientFactory in the JavaCAA zip file.
This reference implementation would be in the org.oasisopen.sca.impl
package, to distinguish it from the APIs and annotations that are
fully standardized and normative.

With this approach, vendors could either use the OASIS reference
implementation directly, or they could replace it with their own
implementation that conforms to the OASIS spec rules for what
this class MUST do.  In either case, client code could call the
SCAClientFactory with confidence that it will do what OASIS says
it will do, i.e., locate a vendor factory provider according to
a given set of rules.  If vendors wanted to add some customization
to SCAClientFactory to fit in with their environment (e.g., better
OSGI support), that would be fine as long as the OASIS rules are
still observed.  We would make sure that the OASIS rules don't
over-constrain the customizations that vendors might want to do.

This might sound similar to Mike's original proposal.  The difference
is the extra level of indirection that it provides.  With Mike's
original proposal, every vendor would ship their proprietary
implementation of the SCAClient class.  These vendor implementations
are not equivalent because they create incompatible client proxies.
If the client has the wrong version of SCAClient on their classpath,
their code won't run.

With the approach I'm sketching out now, every vendor ships two things:
1. A proprietary implementation of their factory provider class,
    under a vendor-specific name (so no classpath ordering conflicts).
2. A proprietary implementation (or the OASIS reference) for the
    SCAClientFactory.  For this, classpath ordering is significant,
    but it shouldn't cause any major problems because all vendor
    implementations of SCAClientFactory will be substitutable for
    each other with respect to the OASIS-defined functionality of
    loading a vendor-specific factory according to some given rules.

With this approach, any client that uses the OASIS SCA client APIs
could run with any vendor's SCAClientFactory and with any vendor's
factory provider, even if these don't come from the same vendor.
For example, the IBM SCAClientFactory would be able to load and
delegate to the Oracle factory provider, and vice versa.  The OASIS
reference implementation for SCAClientFactory would provide a basic
capability to be able to load and delegate to any vendor factory
provider.

   Simon

Mike Edwards wrote:
> 
> Simon,
> 
> The main difference is that the static method in DocumentBuilderFactory 
> provides a mechanism
> for a provider writer to override that default FactoryFinder with 
> another implementation of
> a DocumentBuilderFactory that can itself employ other techniques for 
> loading DocumentBuilders.
> 
> This one-level removed style allows the API code to divorce itself from 
> the techniques of the
> providers - in fact, in our case we could choose to no supply the 
> equivalent of FactoryFinder at
> all - thus requiring some provider to be present.
> 
> Even then it is not perfect, but the other approach is simply to require 
> a provider to supply the
> equivalent of DocumentBuilderFactory "statically" ie via putting that 
> class on the classpath....
> which is where I started.
> 
> 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: 	13/02/2009 17:47
> Subject: 	Re: [sca-j] JAVA-1: Source code for SCAClientFactory proposal 
> - some thoughts
> 
> 
> ------------------------------------------------------------------------
> 
> 
> 
> Mike,
> I had a look at DocumentBuilderFactory and it seems to use code
> that looks very similar to that written by Mark.  This code is
> in another non-public class FactoryFinder that is used by
> DocumentBuilderFactory to delegate the lookup processing.
> 
> What is it specifically about Mark's current proposal that you
> think would be improved by using a DocumentBuilderFactory-like
> approach?  From where I sit, they seem very similar.
> 
>   Simon
> 
> Mike Edwards wrote:
>  >
>  > Mark,
>  >
>  > Thank you for doing this work.
>  >
>  > Unfortunately, it takes us down a path that I am very reluctant to 
> follow.
>  > - Now, in order to provide for alternative implementations, we are
>  > dictating an implementation style that
>  > is inflexible and (based on experience) even hostile to certain
>  > programming environments such as OSGi.
>  >
>  > There are competing concerns here, I realize, and we are going to have
>  > to collectively decide which are
>  > the most important to deal with.
>  >
>  > On the one hand, it is desirable for the client code to have a very
>  > simple and unchanging API to deal with.
>  > This leads to the desire for a concrete class such as the
>  > SCAClientFactory and the return of an object
>  > implementing the desired client API.  All well and good.
>  >
>  > On the other hand, ideally, the actual code used to load the
>  > implementation is created entirely by the
>  > provider, so that the style of loading etc is not dictated by us in the
>  > OASIS TC.
>  >
>  > There seems also the desire to allow multiple different vendor
>  > implementations of providers to be used
>  > simultaneously (eg for access to different domains??).
>  >
>  > The ability to have a simple mechanism to allow a mock provider for
>  > testing purposes...
>  > ( - I'm not sure how your proposal really helps on this one, perhaps you
>  > could explain how it would work)
>  >
>  >
>  > Perhaps a model that might be worth investigating is the one used by the
>  > XML Parsers.
>  > This has a DocumentBuilderFactory which is an Abstract class with no
>  > public constructor - instead it has
>  > a newInstance() method which itself looks for a "real"
>  > DocumentBuilderFactory implementation by
>  > a variety of means.  This allows delegation of the actual factory
>  > behaviour to some implementation,
>  > allowing the OASIS code to shirk the responsibility for this.  It's not
>  > ideal, but it allows us to minimise the
>  > code we write...
>  >
>  >
>  > 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:                  "OASIS Java" <sca-j@lists.oasis-open.org>
>  > Date:                  06/02/2009 10:49
>  > Subject:                  [sca-j] JAVA-1: Source code for 
> SCAClientFactory proposal
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  >
>  >
>  > Hi,
>  >
>  >  
>  >
>  > I have an action item to write some code to show SCAClient as an
>  > interface and SCAClientFactory as a concrete class and still allow
>  > vendors to plug in implementations that provide the vendor specific
>  > functionality.
>  >
>  >  
>  >
>  > The main reasons for doing this include:
>  >
>  >  
>  >
>  >     * Since SCAClient is an interface, it can be mocked for testing
>  >       purposes
>  >     * SCAClientFactory allows vendors to plug in an implementation
>  >       without modifying the SCAClientFactory class
>  >     * The SCA API jar can be shipped without modification by the vendors
>  >
>  >  
>  >
>  > What I will do is run you through the main points of the code and how it
>  > works. The code could do with more polish before it is considered 
> complete.
>  >
>  >  
>  >
>  >  
>  >
>  > *SCA Client Perspective*
>  >
>  >  
>  >
>  > The scenario is fairly simple – some code that is running outside of the
>  > SCA Domain wants to lookup and use a Service that is inside the domain.
>  >
>  >  
>  >
>  > The following code shows how the HelloService could be looked up and
>  > invoked from unmanaged SCA Code.
>  >
>  >  
>  >
>  >         *final* String serviceURI = "SomeHelloServiceURI";
>  >
>  >         *final* URI domainURI = *new* URI("SomeDomainURI");
>  >
>  >        
>  >
>  >         *final* SCAClient scaClient = 
> SCAClientFactory./createSCAClient/();
>  >
>  >         *final* HelloService helloService =
>  > scaClient.getService(HelloService.*class*, serviceURI, domainURI);
>  >
>  >         *final* String reply = helloService.sayHello("Mark");
>  >
>  >  
>  >
>  > The client first calls SCAClientFactory./createSCAClient()/ that returns
>  > an instance of SCAClient. This SCAClient instance can then be used to
>  > look up the HelloService
>  >
>  >  
>  >
>  >  
>  >
>  > *SCAClient Interface*
>  >
>  >  
>  >
>  > The main change from Mike’s original proposal is to make SCAClient an
>  > interface rather than a class. The main reason for this is that it
>  > allows mocking of the SCAClient so that it can be unit tested.
>  >
>  >  
>  >
>  > The new definition of SCAClient interface would be:
>  >
>  >  
>  >
>  > *public* *interface* SCAClient {
>  >
>  >  
>  >
>  >     <_T_> T getService(Class<T> _interfaze_, String serviceURI, URI
>  > domainURI)
>  >
>  >         *throws* _NoSuchServiceException_, _NoSuchDomainException_;    
>  >
>  > }
>  >
>  >  
>  >
>  >  
>  >
>  > *SCAClientFactory class*
>  >
>  >  
>  >
>  > The SCAClientFactory class is responsible for providing the indirection
>  > from the user’s generic SCA code and the vendor’s implementation of the
>  > SCA Runtime. The user’s code will ask it for a SCAClient via the
>  > /createSCAClient/() method.
>  >
>  >  
>  >
>  > The SCAClientFactory class provides this indirection to the vendor’s
>  > implementation by attempting to discover the class name of the vendor’s
>  > implementation using:
>  >
>  >  
>  >
>  >     * The org.oasisopen.sca.SCAClientFactory System Property
>  >     * The META-INF/services/org.oasisopen.sca.SCAClientFactory file.
>  >
>  >  
>  >
>  > It is important to note that this class does not need to be updated by
>  > the Vendor to include their implementation. All the Vendor needs to do
>  > is set the System Property or provide the correct services file
>  >
>  >  
>  >
>  >  
>  >
>  > *What does the Vendor need to do?*
>  >
>  >  
>  >
>  > The Vendor will need to provide a class that will be able to look up a
>  > Service in their SCA Runtime. To do this, they need to:
>  >
>  >  
>  >
>  >     * Provide an implementation of the
>  >       org.oasisopen.sca.SCAClientFactorySPI interface
>  >     * Provide a META-INF/services/org.oasisopen.sca.SCAClientFactory
>  >       file that points to their implementation class
>  >
>  >  
>  >
>  > The SCAClientFactorySPI interface has a single method that the vendors
>  > need to implement:
>  >
>  >  
>  >
>  > *public* *interface* SCAClientFactorySPI {
>  >
>  >  
>  >
>  >     SCAClient _createSCAClient()_;
>  >
>  >  
>  >
>  > }
>  >
>  >  
>  >
>  >  
>  >
>  > *Source Code*
>  >
>  >  
>  >
>  > I have attached a ZIP file that contains the source code for the above.
>  > The ZIP file contains:
>  >
>  >  
>  >
>  > Implementation of SCAClient and SCAClientFactory in the
>  > org.oasisopen.sca package
>  >
>  > Implementation of SCAClientFactorySPI in the org.oasisopen.sca.spi 
> package
>  >
>  >     * A sample implementation of the SCAClientFactorySPI in the
>  >       com.myscaruntime.impl package
>  >     * A unit test that looks up the HelloService using the 
> SCAClientFactory
>  >     * An Eclipse project file
>  >
>  >  
>  >
>  > When loading the Eclipse project file, you may need to set the target
>  > JDK to match the JDK you have installed. To do this simply:
>  >
>  >  
>  >
>  >     * Select the Properties menu item on the Project menu.
>  >     * Select the Java Build Path in the list on the left hand side
>  >     * Select the JRE System Library on the right hand side
>  >     * Press the Edit button
>  >     * Make sure the workspace default JRE is selected and press Finish
>  >     * Press OK
>  >
>  >  
>  >
>  >  
>  >
>  >  
>  >
>  > I would appreciate your thoughts/comments on this proposal.
>  >
>  >  
>  >
>  > 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>
>  >
>  >  
>  >
>  > [attachment "JAVA-1_Code_Proposal.zip" deleted by Mike Edwards/UK/IBM]
>  >
>  > ------------------------------------------------------------------------
>  > ---------------------------------------------------------------------
>  > 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/
>  >
>  >
>  >
>  >
>  >
>  >
> 
> 
> 
> ---------------------------------------------------------------------
> 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/
> 
> 
> 
> 
> 
>