Difference between revisions of "SOAP-based Providers"

From Eclipsepedia

Jump to: navigation, search
 
(7 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
Below is an example of doing this for an existing SOAP-based dictionary service available on the internet.
 
Below is an example of doing this for an existing SOAP-based dictionary service available on the internet.
  
The dictionary service is described [http://services.aonaware.com/DictService/ 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 [http://services.aonaware.com/DictService/DictService.asmx?WSDL here].
+
The dictionary service is described [http://services.aonaware.com/DictService/ 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 Description Language description of this service is available [http://services.aonaware.com/DictService/DictService.asmx?WSDL here].
  
The example is currently located on the [http://ecf1.osuosl.org ECF OSUOSL] site. Here's the CVS information for this site:
+
The example is currently located on [https://github.com/ECF/SOAP https://github.com/ECF/SOAP].:
  
 
<pre>
 
<pre>
anonymous:  :pserver:anonymous@ecf1.osuosl.org:/ecf
+
https://github.com/ECF/SOAP
extssh:  :extssh:ecf1.osuosl.org:/home/cvs/ecf
+
  
 
modules:   
 
modules:   
Line 33: Line 32:
 
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.
 
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.
  
# Create the provider bundle (i.e. in this case '''o.e.e.provider.dictionary.soap.client).   
+
1. Create the provider bundle (i.e. the example is called '''o.e.e.provider.dictionary.soap.client''').   
  
# Using the [http://services.aonaware.com/DictService/DictService.asmx?WSDL dictionary service wsdl], and either the [http://ws.apache.org/axis/ Apache Axis wsdl2java] OR the [http://www.eclipse.org/webtools 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:
+
2. Using the [http://services.aonaware.com/DictService/DictService.asmx?WSDL dictionary service wsdl], and either the [http://ws.apache.org/axis/ Apache Axis wsdl2java] OR the [http://www.eclipse.org/webtools WTP Web Client Wizard] (which, incidently, also uses 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:
  
 
<pre>
 
<pre>
Line 48: Line 47:
 
These libraries are available in the [http://ws.apache.org/axis/ Apache Axis 1.4 distribution].
 
These libraries are available in the [http://ws.apache.org/axis/ Apache Axis 1.4 distribution].
  
# Create an ECF 'container class' that extends the class '''org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientContainer'''
+
3. Create a new class that extends '''org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientContainer'''.  In the example provider, this is the DictionarySoapClientContainer class.
  
# Create a remote service instance class that extend the class '''org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientService'''
+
4. Create a new class in the provider bundle that extends the class '''org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientService'''.  In the example provider, this is the DictionarySoapClientService.
  
# Create a 'container instantiator' class that extends the class '''org.eclipse.ecf.core.provider.BaseContainerInstantiator'''.
+
5. Create a new class that extends '''org.eclipse.ecf.core.provider.BaseContainerInstantiator'''.  In the example provider this is the DictionarySoapClientContainerInstantiator.
  
See the example instances of these classes in the o.e.e.provider.dictionary.soap.client bundle.
+
See the examples in the o.e.e.provider.dictionary.soap.client bundle for understanding the implementation.
  
# Create an extension for the ECF 'containerFactory' extension point, and have it point to the container instantiator class you created...for example
+
6. Create an extension for the ECF 'containerFactory' extension point, and have it point to the container instantiator class you created...for example
  
 
<pre>
 
<pre>
Line 63: Line 62:
 
       <containerFactory
 
       <containerFactory
 
             class="org.eclipse.ecf.examples.internal.provider.dictionary.soap.client.DictionarySoapClientContainerInstantiator"
 
             class="org.eclipse.ecf.examples.internal.provider.dictionary.soap.client.DictionarySoapClientContainerInstantiator"
             name="ecf.dictionary.soap.client">
+
             name="ecf.examples.dictionary.soap.client">
 
       </containerFactory>
 
       </containerFactory>
 
   </extension>
 
   </extension>
 
</pre>
 
</pre>
  
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.
+
At this point, if all the Axis supporting libraries are on the Bundle-Classpath, and the abstract methods have been appropriately implemented, then you are '''done'''.   
  
 
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.
 
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.
 +
 +
Here, for example, is some test code that shows the use of the ECF IDictionary remote service:
 +
 +
<pre>
 +
protected void setUp() throws Exception {
 +
super.setUp();
 +
container = getContainerFactory().createContainer("ecf.examples.dictionary.soap.client");
 +
containerAdapter = (IRemoteServiceContainerAdapter) container.getAdapter(IRemoteServiceContainerAdapter.class);
 +
}
 +
 +
public void testDictionaryService() throws Exception {
 +
IRemoteServiceReference[] refs = containerAdapter.getRemoteServiceReferences((ID) null, IDictionary.class.getName(), null);
 +
assertNotNull(refs);
 +
assertTrue(refs.length > 0);
 +
IRemoteService remoteService = containerAdapter.getRemoteService(refs[0]);
 +
// Get proxy
 +
IDictionary dictionary = (IDictionary) remoteService.getProxy();
 +
// Now call it
 +
WordDefinition def = dictionary.define("abstruse");
 +
 +
assertNotNull(def);
 +
printWordDefinitions(def);
 +
}
 +
 +
</pre>

Latest revision as of 05:18, 20 November 2010

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 Description Language description of this service is available here.

The example is currently located on https://github.com/ECF/SOAP.:

https://github.com/ECF/SOAP

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. the example is called o.e.e.provider.dictionary.soap.client).

2. Using the dictionary service wsdl, and either the Apache Axis wsdl2java OR the WTP Web Client Wizard (which, incidently, also uses 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.

3. Create a new class that extends org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientContainer. In the example provider, this is the DictionarySoapClientContainer class.

4. Create a new class in the provider bundle that extends the class org.eclipse.ecf.remoteservice.soap.client.AbstractSoapClientService. In the example provider, this is the DictionarySoapClientService.

5. Create a new class that extends org.eclipse.ecf.core.provider.BaseContainerInstantiator. In the example provider this is the DictionarySoapClientContainerInstantiator.

See the examples in the o.e.e.provider.dictionary.soap.client bundle for understanding the implementation.

6. 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.examples.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 appropriately implemented, then you are done.

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.

Here, for example, is some test code that shows the use of the ECF IDictionary remote service:

 	protected void setUp() throws Exception {
		super.setUp();
 		container = getContainerFactory().createContainer("ecf.examples.dictionary.soap.client");
 		containerAdapter = (IRemoteServiceContainerAdapter) container.getAdapter(IRemoteServiceContainerAdapter.class);
	}
 	
 	public void testDictionaryService() throws Exception {
 		IRemoteServiceReference[] refs = containerAdapter.getRemoteServiceReferences((ID) null, IDictionary.class.getName(), null);
 		assertNotNull(refs);
 		assertTrue(refs.length > 0);
 		IRemoteService remoteService = containerAdapter.getRemoteService(refs[0]);
 		// Get proxy
 		IDictionary dictionary = (IDictionary) remoteService.getProxy();
 		// Now call it
 		WordDefinition def = dictionary.define("abstruse");
 		
 		assertNotNull(def);
 		printWordDefinitions(def);
 	}