[JAVA-1] Updated code proposal

Hi,

 

I have updated the code for JAVA-1 based on our recent
discussions to include the following requested changes:

 

 
Renamed the SCAClientFactory.createInstance() method
     to SCAClientFactory.newInstance()

 
Added SCAClientFactory.newInstance(Properties) method

 
Added SCAClientFactory.newInstance(ClassLoader) method

 
Added SCAClientFactory.newInstance(Properties,
     ClassLoader) method

 
Added defaultFactory static
     field to SCAClientFactory so
     that Vendors may inject a default implementation.

 
Updated the SCAClientFactoryFinder to
     make use of the specified ClassLoader and
     Property objects if they are specified.

 

This will also complete my action item 2009-02-19-01

 

Code Overview

 

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.newInstance();

       
final HelloService
helloService = scaClient.getService(HelloService.class, serviceURI, domainURI);

       
final String reply =
helloService.sayHello("Mark");

 

The client first calls SCAClientFactory.newInstance() that
returns an instance of SCAClient. This SCAClient instance can then be used to look
up the HelloService

 

 

SCAClient Interface

 

The 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 abstract 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 newInstance() method.

 

The SCAClientFactory class
provides this indirection to the vendor’s implementation by:

 

 
if a defaultFactory has
     been injected then use it.

 
If no defaultFactory has
     been injected then delegate to the SCAClientFactoryFinder

 

The code for the SCAClientFactory is now quite short and consists of
(I’ve trimmed the JavaDoc to make it easer to read in this email)

 

public abstract class
SCAClientFactory {

 

    private static
SCAClientFactory defaultFactory; 

 

    public static SCAClient
newInstance() {

        return newInstance(null, null);

    }

 

    public static SCAClient
newInstance(Properties properties) {

        return newInstance(properties,
null);

    }

 

    public static SCAClient
newInstance(ClassLoader classLoader) {

        return newInstance(null, classLoader);

    }

 

    public static SCAClient
newInstance(Properties properties, ClassLoader classLoader) {

        final SCAClientFactory factory;

        if(defaultFactory == null) { 

           
factory = SCAClientFactoryFinder.find(properties,
classLoader); 

        } else { 

           
factory = defaultFactory; 

        }

        return factory.createSCAClient();

    }

 

    protected abstract SCAClient
createSCAClient();

}

 

 

SCAClientFactoryFinder class

 

SCA will provide a reference
implementation of the SCAClientFactory class. It
will discover the Vendors SCAClientFactory
implementation by referring to the following information:

 

 
The org.oasisopen.sca.SCAClientFactory property
     from the Properties specified on the newInstance() method
     call if specified

 
The org.oasisopen.sca.SCAClientFactory property
     from the System Properties

 
The META-INF/services/org.oasisopen.sca.SCAClientFactory file

 

Since this is a reference
implementation Vendors are free to replace the SCAClientFactoryFinder class with
an alternative implementation that meets the lookup mechanisms require for their
SCA Runtime.

 

 

What does the
Vendor need to do?

 

Implement their SCAClientFactory and SCAClient implementation classes

 

Vendors need to provide an implementation of SCAClient that is
capable of looking up Services in their SCA Runtime.

 

Vendors need to subclass SCAClientFactory
and implement the createSCAClient() method so that it creates an
instance of their SCAClient implementation.

 

 

Configure the Vendor Implementation classes
so they are used

 

Vendors have two options:

 

Option 1: Use the reference
implementation of SCAClientFactoryFinder

 

Vendors will specify their Implementation class by any of
the following methods:

 
Provide a META-INF/services/org.oasisopen.sca.SCAClientFactory file
     that points to their implementation class 

 
Set the org.oasisopen.sca.SCAClientFactory System
     Property to point to their implementation class

 
Inject an instance into the defaultFactory field
     of SCAClientFactory

 

Option 2: Provide a Vendor specific implementation of SCAClientFactoryFinder

 

Vendors will need to write a new implementation of SCAClientFactoryFinder and replace
the reference implementation that
is provided by SCA.

 

This approach allows the Vendor complete flexibility as to
how SCAClient instances are created.

 

 

Source Code

 

I have attached a ZIP file that contains the source code,
unit tests and an Eclipse project file for JAVA-1.

 

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 am planning to add this issue to the agenda for Monday’s
call as it is too late to add it to today’s call and expect people to
have read/reviewed it.

 

 

I would appreciate your thoughts/comments on this updated proposal.

 

Thanks,

 

Mark

Mark Combellack| Software Developer| Avaya | Eastern Business Park | St. Mellons | Cardiff |
CF3 5EA | Voice: +44 (0) 29 2081 7624 | 

JAVA-1_Code_Proposal_v2.zip