UNO Web Service Proxy

1. Introduction

Web services are more and more emerging. Some examples are Google and Amazon which are providing a Web service interface for their traditional services, like searching the Web or querying the online bookstore. These interfaces could now be reached by UNO and StarBasic over the UNO Web service proxy. The access with StarBasic is very convenient because of special features of the StarBasic-UNO language binding, as you can see in the given examples.

The component is developed in Java and uses the Java^TM Web Services Developer Pack (JWSDP) 1.0_01 [JWSDP]. It adds more functionality in terms of dynamically invoking Web services. Thus one could provide at any time a Web service description defined with the Web Service Description Language (WSDL) and one could access its interfaces.

2. Architecture

The main entry point is the ProxyFactory, which is a realization of the UNO interface com.sun.star.webservices.proxy.XProxyFactory . A WSDL [CHRI01] must be provided for instantiating the ProxyFactory, thus the ProxyFactory could consume the WSDL for getting extended reflection and type information. Each Web service -based on WSDL- consists of a number of services. In turn each service holds ports. Thus a caller receives an object from the class InvocationProxy, which is a mapping of the requested port inside a service. After this step the caller could call the methods of the Web service through the InvocationProxy.

The following examples are given in StarBasic code. The examples are working with the Google^TM Web APIs service [GOOG02]. You need to register at http://www.google.com/apis in order to be able to get access.

'Getting the UNO service
proxyFac = createUNOService("com.sun.star.webservices.proxy.ProxyFactory")

' Initializing of the ProxyFactory by providing the WSDL:
proxyFac.initialize(Array("http://api.google.com/GoogleSearch.wsdl "))

'Getting the proxy for the Web service by providing the
'serviceNamespace, serviceName, portNamespace and the portName respectively.
'All parameters, except the namespaces which is the targetNamespace of the WSDL,
'are specified in the service description part of the WSDL.
proxy = proxyFac.getProxy("urn:GoogleSearch", "GoogleSearchService", "urn:GoogleSearch", "GoogleSearchPort")

Basic example for the initializing of the ProxyFactory and the InvocationProxy

Because the InvocationProxy implements the XInvocation interface, in Basic the call of a Web service is looking like an ordinary call of a function:

' The Web service returns an XPropertySet.
' One could call the methods specified in the message description section of the WSDL.
' GOOGLE_KEY is in this example a key which was received from google. (http://www.google.com/apis)
propertySet = proxy.doGoogleSearch(GOOGLE_KEY, "Peace" , 0, 10, false, "", false, "","latin1", "latin1")

Example for calling the Web service and receiving the return value

If the Web service is returning a complex data type, it is returned by the component as an XPropertySet. Thus one could easily access the members of the complex type, by referring to the names of the members.

'This shows all the properties of this XPropertySet
msgbox propertySet.dbg_Properties

'resultSet is an array of XPropertySet's
resultSet = propertySet.resultElements

'This for loop shows a snippet of the search result
for i= 0 to UBound(resultSet)
msgbox resultSet(i).snippet
next i

Example of processing the received XPropertySet

If the user of the component needs to provide a complex type, one could first create the complex type by calling the method createComplex on the ProxyFactory. One must provide the full qualified name, by including the XML namespace and the localname [BRAY99] for this complex data type. Both , the namepace and the localname are part of the WSDL. The method returns again an XPropertySet, where the user could access the member of the PropertySet. The names of the members are the corresponding names of the complex data type given in the WSDL.

<complexType name="MyBean">
   <sequence>
     <element name="b" type="string"/>
     <element name="a" type="soap-enc:int"/>
   </sequence>
</complexType>

XML example for a complex data type

3. Type Mapping

The illustration above shows all the involved components. Because there exists no equal types in every component (UNO, JWSDP or SOAP) for the simple and complex types of a Web service, a type mapping is needed. The following table describes the type mapping between the XML types, transfered with SOAP, the JWSDP and the UNO/StarBasic types.

XML schema data types^*

JWSDP

UNO

xsd:string

java.lang.String

string

xsd:integer

java.math.BigInteger

-not supported-

xsd:int

int

long

xsd:long

long

hypher

xsd:shor

short

short

xsd:decimal

java.math.BigDecimal

-not supported-

xsd:float

float

float

xsd:double

double

double

xsd:boolean

boolean

boolean

xsd:byte

byte

byte

xsd:QName

javax.xml.namespace.QName

-not supported-

xsd:dateTime

java.util.Calendar

-not supported-

xsd:base64Binary

byte[]

sequence<byte>

xsd:hexBinary

byte[]

sequence<byte>

soapenc:string

java.lang.String

string

soapenc:boolean

java.lang.Boolean

boolean

soapenc:float

java.lang.Float

float

soapenc:double

java.lang.Double

double

soapenc:decimal

java.math.BigDecimal

-not supported-

soapenc:int

java.lang.Integer

long

soapenc:short

java.lang.Short

short

soapenc:byte

java.lang.Byte

byte

soapenc:base64

byte[]

sequence<byte>

* XML schema data types as specified in the XML Schema specifications, Part 1 [SCHEMA1] and Part 2 [SCHEMA2], and SOAP 1.1 encoding specification [SOAP1.1].

4. To Do

• Writing a sophisticated basic demo which uses the component.

• Adding support anonymous complex types, which could occur in a WSDL, inside element tags.

<xsd:element name="GetFedACHCities">
   xsd:complexType>
     <xsd:sequence>
       <xsd:element minOccurs="0" maxOccurs="1" name="state" type="xsd:string"/>
     </xsd:sequence>
   </xsd:complexType>
</xsd:element>

Example of an anonymous complex type inside element tags

• In/ Out parameters are not yet implemented.

  
  

5. Download/ Installing Instructions

You need -at least- the developer build 643C of OpenOffice.org and the requirements defined by the JWSDP.

1. Download and install the Java^TM Web Services Developer Pack 1.0_01 [JWSDP].

2. Download the UNO Web service proxy(58k) component.

3. Optional: Download the UNO Web service proxy example. Please read the instructions inside the document.

4. For UNIX users: Add the following path to your SystemClasspath property inside the javarc (<office_dir>/user/config/javarc) :

4. Please replace <your-jwsdp-installation-path> with the installation path of the JWSDP and be sure that there are no spaces after the semicolons!

5. For UNIX users: Additionally you have to add some classes to the Xbootclasspath, please add the following line at the end of your javarc file.

5. Again, replace <your-jwsdp-installation-path> with the installation path of the JWSDP .
   This step is needed because of a bug in OpenOffice.org 643C. In future versions of OpenOffice.org this step may be omitted and the path should then be added to the SystemClasspath property.

6. Install the component with the pkgchk tool.

   UNIX users type:

Now you could test the installation of the component by typing the following lines of code inside a StarBasic module:

proxyFac = createUNOService("com.sun.star.webservices.proxy.ProxyFactory")

msgbox proxyFac.dbg_supportedinterfaces

If there appears a message box with all the supported interfaces of the ProxyFactory you have successfully installed the component. Congratulations!

6. Source Code

If you are interested in the source of this project, please refer to: http://udk.openoffice.org/source/browse/udk/soap/proxy/src/

7. References

[BRAY99]
Bray, T., Hollander, D., & Layman, M. (January 14, 1999). Namespaces in XML. (W3C Recommendation). Retrieved Dec. 13, 2002 from
http://www.w3.org/TR/1999/REC-xml-names-19990114

[CHRI01]
Christensen, E., Curbera, F., Meredith, G., & Weerawarana, S. (March 15, 2001). Web Services Description Language (WSDL) 1.1. (W3C Note). Retrieved Dec. 13, 2002 from http://www.w3.org/TR/2001/NOTE-wsdl-20010315

[GOOG02]
WSDL description of the Google Web APIs. (August 16, 2002). Retrieved Dec. 06, 2002 from
http://api.google.com/GoogleSearch.wsdl

[JAXRP02]
Sharma, R. (June 11. 2002). Java^TM API for XML-based RPC. JAX-RPC 1.0. Retrieved Dec. 20. 2002 from
http://java.sun.com/xml/downloads/jaxrpc.html

[JWSDP]
Java^TM Web Services Developer Pack v.1.0_01. Retrieved Aug. 22, 2002 from
http://java.sun.com/webservices/webservicespack.html

[SCHEMA1]
W3C XML Schema Working Group. (May 2, 2001). Schema Part 1: Structures. (W3C Recommendation). Retrieved Dec. 30. 2002 from
http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/

[SCHEMA2]
W3C XML Schema Working Group. (May 2, 2001). XML Schema Part 2: Datatypes. (W3C Recommendation). Retrieved Dec. 30. 2002 from
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/

[SOAP1.1]
Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendelsohn, N., Nielsen, H. F., et al. (May 08. 2000). Simple Object Access Protocol (SOAP) 1.1. (W3C Note). Retrieved Dec. 30. 2002 from http://www.w3.org/TR/2000/NOTE-SOAP-20000508

Author: Jan Tietjens ($Date: 2002/12/27$)
Copyright 2002 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.