Content starts here Web Services Map File Reference
This page last changed on Feb 26, 2008.

eDocs Home > BEA AquaLogic Data Services Platform Documentation > Data Services Developer's Guide > Contents

Web Services Map File Reference

The web services map file is an XML file that provides an explicit mapping between ALDSP data service functions and web service operations. The map file is the basis for generating the WSDL that describes the web services interface for a data service. This section discusses the configurable parts of the map file in detail. For details on creating a map file, see the topic Generate a Web Service Map from a Data Service.

Topics

Map File-Level Properties

The ALDSP Eclipse IDE lets you create the web services map file (as explained in Generate a Web Service Map From a Data Service) and configure the map file. The New Web Service Map wizard creates a .ws file in a specified location within the Dataspace project. This section describes the configurable map file properties. To configure these properties, use the Properties editor in the IDE.

The following figure shows a sample map file that maps functions from a data service called Customer.ds. To view properties for a map file, select the map file in the IDE and select Window > Show View > Properties.

Map File-Level Properties

The following table describes each of the map file properties.

Map File Properties
Property 
Description
ADO.net Enabled If enabled, a .NET style WSDL is generated. This WSDL includes .NET datasets in the WSDL construct. Disabled by default. For more information on ADO.NET, see the Client Application Developer's Guide.
Basic Auth Required If true, basic authentication is required to access the WSDL operations.
Map Name    (Read-only) The name of the map file.
SOAP Version SOAP 1.1 and 1.2 are supported. The version is used by ALDSP to decide which kind of SOAP binding to create during WSDL generation. The default is 1.1.  SOAP 1.2 encoding is not supported. Encoding is an optional feature defined by the SOAP 1.2 specification.
Target Name Space The default value is generated from the web service based on the location of the map file and the file name.
Transport Type HTTP and HTTPS are the only supported types. Default is HTTP.
Policies    Lets you specify security policies that apply to all the functions in the map. For information on policies, see the topic Configure Security for Web Services Applications.

Operation Level Properties

This section describes the operation-level properties that you can modify in the IDE. Operations match up with data service functions. Each data service function maps to a WSDL operation. Operation-level properties apply to the specific operation only.

The following figure shows the properties displayed for a selected data service function. To view properties for a data service operation, select the operation in the IDE and select Window > Show View > Properties.

Operation-Level Properties

The following table describes each of the operation properties.

Map File Properties
Property    
Description
Data Service Name Read-only.
Function Name Read-only.
Operation Name The WSDL operation name that is used to generate a WSDL. This name has to be unique within the map file.
Return Type Maps the WSDL operation return type to either a SOAP header or body.
Parameters    Lists all parameters for the operation and lets you map each parameter to either a SOAP header or body.
Policies    Lets you specify security policies that apply to the operation. For information on policies, see the topic Configure Security for Web Services Applications.

Map File XML Schema Definition

The following listing shows the schema file for the map (.ws file) definition.

Web Services Map File Schema Definition


<xs:schema
targetNamespace="http://www.bea.com/dsp/management/configuration/webservices"
 xmlns:tns="http://www.bea.com/dsp/management/configuration/webservices"
 xmlns="http://www.bea.com/dsp/management/configuration/webservices"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 elementFormDefault="qualified">

  <xs:element name="WebServicesMap">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="policies" type="PoliciesType"
                    minOccurs="0"/>
        <xs:element name="dataServices"
                    type="DataServicesType"/>
      </xs:sequence>
      <xs:attribute name="targetNamespace" type="xs:anyURI"
                    use="required"/>
      <xs:attribute name="soapVersion" type="SoapVersionType"
                    default="SOAP_1.1"/>
      <xs:attribute name="transportType" type="TransportTypeType"
                    default="HTTP"/>
      <xs:attribute name="ADODotNETEnabled" type="xs:boolean"
                    default="false"/>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name="SoapVersionType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="SOAP_1.1"/>
      <xs:enumeration value="SOAP_1.2"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="TransportTypeType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="HTTP"/>
      <xs:enumeration value="HTTPS"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="PoliciesType">
    <xs:sequence>
      <xs:element name="policy" type="PolicyType" minOccurs="1"
                  maxOccurs="unbounded"/>

    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="PolicyType">
    <xs:attribute name="locator" type="xs:string" use="required"/>
    <xs:attribute name="direction" type="PolicyDirectionType"
              default="REQUEST_RESPONSE"/>

  </xs:complexType>

  <xs:simpleType name="PolicyDirectionType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="REQUEST"/>
      <xs:enumeration value="RESPONSE"/>
      <xs:enumeration value="REQUEST_RESPONSE"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="DataServicesType">
    <xs:sequence>
      <xs:element name="dataService" type="DataServiceType"
                  minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="DataServiceType">
    <xs:sequence>
      <xs:element name="function" type="FunctionType" minOccurs="1"
                  maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="locator" type="xs:string" use="required"/>
  </xs:complexType>

  <xs:complexType name="FunctionType">
   <xs:sequence>
    <xs:element name="policies" type="PoliciesType" minOccurs="0"/>
    <xs:element name="parameterMapping" type="ParameterMappingType"
           minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="name" type="xs:string" use="required"/>
    <xs:attribute name="arity" type="xs:integer" use="required"/>
<xs:attribute name="operation" type="xs:string" use="required"/>
<xs:attribute name="returnInHeader" type="xs:boolean"
             default="false"/>
  </xs:complexType>

  <xs:complexType name="ParameterMappingType">
    <xs:sequence>
      <xs:element name="parameter" type="ParameterType" minOccurs="1"
                  maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="ParameterType">
    <xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="wsdlMapping" type="WSDLMappingType"
              use="required"/>
  </xs:complexType>

  <xs:simpleType name="WSDLMappingType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="SOAP_HEADER"/>
     <xs:enumeration value="SOAP_BODY"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>


How Data Service Types Map to WSDL Message Types

This section explains how data service types are mapped to WSDL message types when you map a data service function to a WSDL operation.

Two Schema Elements Per Function

For each data service function, two WSDL schema elements are generated. The first element is the name of the request message, and it is the same as the data service function name that is mapped to the WSDL message. The second represents the response message. The response message name is the same as the function name with "Response" appended to it. The following listing shows an example schema where getCustomer is the request name and getCustomerResponse is the response name. The response element contains the return type of the data service function, which can be complex or simple.

Operation Element and Return Element
<types>
  <xsd:schema targetNamespace="ld:DataServices/RTLServices/Customer.ws"
              xmlns:dsns0="urn:retailerType">
  <xsd:import namespace="urn:retailerType"/>

  <xsd:element name="getCustomer">
    <xsd:complexType>
      <xsd:sequence/>
    </xsd:complexType>
  </xsd:element>

  <xsd:element name="getCustomerResponse">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="dsns0:CUSTOMER_PROFILE" minOccurs="0"
                     maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</types>

Mapping of Update Functions with DataGraphs

This section explains how a data service update operation's parameters and return type are mapped to a WSDL schema definition.  

Consider the following data service definition for an operation called updateADDRESS:

(::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com"
visibility="public" kind="update" isPrimary="true" nativeName="ADDRESS"
nativeLevel2Container="RTLCUSTOMER" style="table">

<nonCacheable/>   </f:function>::)


   declare procedure f1:updateADDRESS($p as changed-element(t1:ADDRESS)*) as empty()  external;

Note that the operation's parameter type is changed-element(UserType). In this case the element is ADDRESS. The changed-element type is translated to a DataGraph in the WSDL schema. The WSDL schema must also include a schema definition for the DataGraph. The following listing shows the translated updateADDRESS operation and the schema definition for the DataGraph.

WSDL Schema for an Update Operation
<xs:element name="updateADDRESS">
<xs:complexType>
<xs:sequence>
<xs:element name="p">
<xs:complexType>
<xs:sequence>
  <xs:element ref="dsns0:ADDRESSDataGraph" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
    </xs:complexType>
    </xs:element>
    </xs:sequence>
    </xs:complexType>
    </xs:element>
<xs:element name="updateADDRESSResponse">
<xs:complexType>
    <xs:sequence />
    </xs:complexType>
    </xs:element>
...
<xs:schema targetNamespace="ld:ADDRESS" xmlns:dsns0="ld:ADDRESS"    xmlns:sdo="commonj.sdo">
  <xs:import namespace="commonj.sdo"      schemaLocation="http://www.osoa.org/sdo/2.1/schemas/datagraph.xsd" />
  <xs:element name="ADDRESSDataGraph" type="dsns0:ADDRESSDataGraphType" />
<xs:complexType name="ADDRESSDataGraphType">
<xs:complexContent>
<xs:extension base="sdo:BaseDataGraphType">
<xs:sequence>
  <xs:element ref="dsns0:ADDRESS" />
    </xs:sequence>
    </xs:extension>
    </xs:complexContent>
    </xs:complexType>
    </xs:schema>
...

Overloading Data Service Functions

Data service functions can be overloaded, meaning that two functions in the same data service have the same name but a different number of parameters. For example, in the following listing two getCustomer() functions are declared, each with a different parameter set. To support WSDL generation for overloaded data service functions, the web services map requires the overloaded function to be mapped to a different WSDL operation. In other words, if you drag two functions with the same name from a data service onto a web service map file, ALDSP generates different WSDL operation names for the two functions. You can accept the default names or change them.

Overloaded Functions
declare function ns9:getCustomer() as element(ns2:CUSTOMER_PROFILE)*

declare function ns9:getCustomer($customerID as xs:string) as element(ns2:CUSTOMER_PROFILE)*

Examining the Generated WSDL

You can examine the generated WSDL file.  The dataspace project's associated WebLogic server must be started and the dataspace project be deployed to the server to view the WSDL or test the Web Service.

  1. Right-click on the web service file name (example: CUSTOMER.ws)
  2. Choose:
View WSDL

The WSDL will appear in its own window in the work area.

View of Generated WSDL

You can also request the WSDL for a deployed project by entering the following URL:

http://host:port/dataSpaceProjectName/folderName/.../mapFileName.ws?WSDL

For example:

http://localhost:7001/myDataSpace/myWSMapper.ws?WSDL

Testing the Generated WSDL

You can test the generated WSDL file using these steps. The dataspace project's associated WebLogic server must be started and the dataspace project be deployed to the server to view the WSDL or test the Web Service.

  1. Right-click on the web service file name (example: CUSTOMER.ws)
  2. Choose:
Test Web Service

The WSDL will appear in its own window.

View of Tested Web Service

Copying and Saving a WSDL Generated from a Map

 
You can copy or save a WSDL by right-clicking the map file and selecting Copy WSDL URL or Save WSDL As.

  
Document generated by Confluence on Apr 28, 2008 15:57