Web Services Map File Reference This page last changed on Nov 28, 2008. .stickable, h1, h2, h3, h4, h5 false true Show Sticky notes Hide Sticky notes Save Cancel Oracle Data Service Integrator Documentation > Data Services Developer's Guide # Web Services Map File Reference The web services map file is an XML file that provides an explicit mapping between Oracle Data Service Integrator 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 Operation Level Properties Map File XML Schema Definition How Data Service Types Map to WSDL Message Types Examining the Generated WSDL Testing the Generated WSDL Copying and Saving a WSDL Generated from a Map ## Map File-Level Properties The Oracle Data Service Integrator 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 Oracle Data Service Integrator 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.oracle.com/dsp/management/configuration/webservices"
     xmlns:tns="http://www.oracle.com/dsp/management/configuration/webservices"
     xmlns="http://www.oracle.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 Mapping of Update Functions with DataGraphs Overloading Data Service Functions ### 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.oracle.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, Oracle Data Service Integrator 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 Oracle WebLogic server must be started and the dataspace project be deployed to the server to view the WSDL or test the Web Service. Right-click on the web service file name (example: CUSTOMER.ws) 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 Oracle WebLogic server must be started and the dataspace project be deployed to the server to view the WSDL or test the Web Service. Right-click on the web service file name (example: CUSTOMER.ws) 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 Jan 13, 2009 15:57