SOAP-based Providers

With ECF 3.2, one can create client providers that implement SOAP-based protocols.

Below is an example of doing this for an existing SOAP-based dictionary service available on the internet.

The dictionary service is described here. It's a simple dictionary service...given a word, it returns the definitions available for that word (there are other functions in the API, but for the purposes of simplifying this example only the definition service will be implemented). The Web Service Discription Language description of this service is available here.

The example is currently located on the ECF OSUOSL site. Here's the CVS information for this site:

anonymous:  :pserver:anonymous@ecf1.osuosl.org:/ecf
extssh:  :extssh:ecf1.osuosl.org:/home/cvs/ecf

modules:  
examples/bundles/org.eclipse.ecf.examples.remoteservices.dictionary.common
examples/bundles/org.eclipse.ecf.examples.provider.dictionary.soap.client
examples/bundles/org.eclipse.ecf.examples.tests.remoteservices.dictionary.soap.client

These three example bundles depend upon several of the ECF sdk bundles, these can be retrieved via the instructions on this page.

Below is a short description of how this provider was created.

1. Define the service API and create a 'common' bundle for it. If the dictionary service, the dictionary OSGi service was defined as

public interface IDictionary {

	public WordDefinition define(String word);
	
}

This IDictionary interface and the WordDefinition class are the entire contents of the bundle o.e.e.examples.remoteservices.dictionary.common. These two classes define the service API.

1. Create the provider bundle (i.e. in this case o.e.e.provider.dictionary.soap.client).

1. Using the dictionary service wsdl, and either the Apache Axis wsdl2java OR the WTP Web Client Wizard (which, incidently, also usese Apache Axis' wsdl2java generator), generate the client java code into the new provider bundle. Also, to get the generated code to compile in the bundle, you will add the supporting Axis libraries to the bundle, and then make these libraries available on the Bundle-Classpath in the bundle's manifest.mf. For example, here is part of the manifest.mf for the example provider:

Bundle-ClassPath: lib/axis.jar,
 lib/commons-discovery-0.2.jar,
 lib/commons-logging-1.0.4.jar,
 lib/jaxrpc.jar,
 lib/saaj.jar,
 lib/wsdl4j-1.5.1.jar,

These libraries are available in the Apache Axis 1.4 distribution.

1. Create an ECF 'container class' that extends the class org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientContainer

1. Create a remote service instance class that extend the class org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientService

1. Create a 'container instantiator' class that extends the class org.eclipse.ecf.core.provider.BaseContainerInstantiator.

See the example instances of these classes in the o.e.e.provider.dictionary.soap.client bundle.

1. Create an extension for the ECF 'containerFactory' extension point, and have it point to the container instantiator class you created...for example

   <extension
         point="org.eclipse.ecf.containerFactory">
      <containerFactory
            class="org.eclipse.ecf.examples.internal.provider.dictionary.soap.client.DictionarySoapClientContainerInstantiator"
            name="ecf.dictionary.soap.client">
      </containerFactory>
   </extension>

At this point, if all the Axis supporting libraries are on the Bundle-Classpath, and the abstract methods have been implemented, then you are done. See the examples listed above for an example of how to implement the various abstract methods.

The test bundle org.eclipse.ecf.examples.tests.remoteservices.dictionary.soap.client has a junit test case that shows the use of the newly created provider to use the IDictionary remote service proxy.