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

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

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