10 Preparing Services for Clients

This chapter describes how to prepare client JAR files and web service maps for client applications. This chapter includes the following sections:

10.1 Generating a Mediator Client JAR File

To use the Static Mediator API in a client application, you must generate a Mediator Client JAR file. This JAR file contains the Static Mediator API interfaces, plus all the necessary SDO-compiled schemas for a dataspace.

One Java method is generated for each mapped data service operation. Method names match the mapped data service operation names. Client developers access data service operations by calling these methods.

This section explains how to generate a Mediator Client JAR by these two methods:

Note:

You can also generate a Mediator Client JAR using the Administration Console. See the Oracle Data Service Integrator Administration Guide for details.

10.1.1 Using the IDE

To generate a mediator client JAR file using the IDE:

  1. Select File > Export.

  2. In the Export dialog, select Oracle Data Service Integrator > Mediator Client JAR File.

  3. Click Next.

  4. Complete the Mediator Client JAR File dialog as follows:

    1. Select a Dataspace project to export. You can only select one Dataspace project at a time.

    2. Specify a directory in which to place the exported JAR file. You can use the drop down list to select a recently specified directory or use the Browse button to locate one.

    3. Unselect the Use default name checkbox if you want to enter a name for the JAR file.

    4. Click Finish to create the JAR file.

      The Oracle Data Service Integrator Console view displays the export task status and any errors that may have occurred. You can click the Cancel button to cancel the export task before it has completed.

10.1.2 Using the Command-Line Tool

This section explains how to generate a Mediator Client JAR file using the command-line tool. Before using the command-line tool, be sure you have the following:

  • Oracle WebLogic Server 10.3 installed with Oracle Data Service Integrator installed in the default location BEA_HOME/odsi_10.3.

  • A Dataspace project on your local file system that contains data service (.ds) and schema (.xsd) files. Miscellaneous IDE files within the project folder are allowed and will not affect the export.

  • Ant installed and in your path.

To generate the client JAR, use this Ant command:

ant -Dapproot=PROJECT_HOME -f BEA_HOME/odsi/bin/sdo_dspclientgen.xml

where PROJECT_HOME is the full path to the Data Space project's root folder, and BEA_HOME is the root path for your Oracle WebLogic installation.

For example (all on one line):

ant -Dapproot=/home/myprojects/myapp -f /home/bea/odsi/bin/sdo_dspclientgen.xml

This Ant script produces a file named PROJECTNAME-dsp-client.jar in PROJECT_HOME, where PROJECTNAME is the name of the directory PROJECT_HOME (as opposed to the full path to that directory). For example, the above script produces the Mediator Client JAR file:

/home/myprojects/myapp/myapp-dsp-client.jar.

Optional command-line features include:

  • Your environment must contain a WL_HOME environment variable, pointing to the WLS 9.2 installation. If it does not, you can provide an alternate by adding -Dwl.home=/path to specify the WLS root directory.

  • Your Oracle Data Service Integrator installation must be in the default directory BEA_HOME/odsi_10.3. If it is not, you can provide an alternate by adding -Ddsp.home=/path to specify the directory.

  • To specify a full directory path for the output, add -Doutdir=/dirpath to the Ant command. You must provide an absolute path; a relative path, including ".", will not work, as it is assumed to be relative to PROJECT_HOME.

  • To specify a different name for the JAR file, add -Dsdojarname=name.jar.

10.2 Generating a Web Services Mediator Client JAR File

This section explains how to generate a Web Services Mediator Client JAR file. This JAR is required by developers writing Java clients that access data services through web services using the Static Mediator API.

This section includes these sections:

10.2.1 Overview

To use the Static Mediator API in a web services-enabled client application, you must generate a Web Services Mediator Client JAR file. This JAR file contains the Static Mediator API interfaces, plus all the necessary SDO-compiled schemas for a dataspace.

One Java method is generated for each data service function that is mapped to a WSDL operation. Method names match the mapped WSDL operation name. Client developers access data service functions through the web service by calling these methods. If the web service requires message-level security, you can add a credential provider and trust manager through initial context properties. For more information on security, see Configure Security for Web Services Applications.

Note:

You can also generate a Mediator Client JAR using the Administration Console. See the Oracle Data Service Integrator Administration Guide for details.

10.2.2 Using Eclipse for WebLogic

To generate a Web Services Mediator Client JAR file using Eclipse for WebLogic:

  1. Select File > Export.

  2. In the Export dialog, select Oracle Data Service Integrator > Web Services Mediator Client JAR File.

  3. Click Next.

  4. Complete the Web Services Mediator Client JAR File dialog as follows:

    1. In the left panel, select the Dataspace project that contains the .ws file(s) to export. You can only export .ws files in one Dataspace project at a time. Checking or unchecking the checkbox next to a project or a folder automatically checks or unchecks all the sub-folders and .ws files under that project/folder.

    2. In the right panel, select the Web Service Map file to export. You can select one or more .ws files. To see and selectively check the .ws files in a sub-folder, expand and click on the folder on the left panel. The message under the right panel shows the total number of .ws files currently checked for export.

    3. Specify a directory in which to place the exported JAR file. You can select any location on your system. You can use the dropdown list to select a recently specified directory or use the Browse button to locate one. By default, the exported JAR will be named: <data_space_name>-ws-client.jar.

    4. Unselect the Use default name checkbox if you want to enter a name for the JAR file.

  5. Click Finish.

    The Oracle Data Service Integrator Console view displays the export task status and any errors that may have occurred. You can click the Cancel button to cancel the export task before it has completed.

10.2.3 Using the Command-Line Tool

This section explains now to generate the Web Services Mediator Client JAR file using Ant and presents example Ant commands. Before using the command-line tool, be sure you have the following:

  • Oracle WebLogic Server 10.3 installed with Oracle Data Service Integrator installed in the default location BEA_HOME/odsi_10.3.

  • A Dataspace project on your local filesystem that contains data service (.ds) and schema (.xsd) files. Miscellaneous IDE files within the project folder are allowed and will not affect the export.

  • Ant installed and in your path.

To generate the client JAR, use this Ant command:

ant -Dapproot=PROJECT_HOME -Dwslocator=locator -f BEA_HOME/odsi_10.3/bin/sdo_dspclientgen.xml

Where:

  • PROJECT_HOME is the path to the Dataspace project. You must specify a full path for the values of BEA_HOME and PROJECT_HOME.

  • The locator option takes one of these values:

    • d:URI - Specifies a URI (or a semicolon-separated or space-separated list of URIs) to a .ws file in the Dataspace project from which to generate the JAR file. For example:

      ld:MediatorTestDataServices/CustomerWeb.ws

    • ALL - Generates the JAR for all .ws files in the dataspace.

      The result of executing this Ant script is a file named PROJECT-ld-client.jar in PROJECT_HOME, where PROJECT is the name of the directory PROJECT_HOME (as opposed to the full path to that directory).

Optional command-line features include:

  • Your environment must contain a WL_HOME environment variable, pointing to the WLS 9.2 installation. If it does not, you can provide an alternate by adding -Dwl.home=/path to specify the WLS root directory.

  • Your Oracle Data Service Integrator installation must be in the default directory BEA_HOME/odsi_10.3. If it is not, you can provide an alternate by adding -Ddsp.home=/path to specify the directory.

  • To specify a full directory path for the output, add -Doutdir=/dirpath to the Ant command. You must provide an absolute path; a relative path, including ".", will not work, as it is assumed to be relative to PROJECT_HOME.

  • To specify a different name for the JAR file, add -Dsdojarname=name.jar.

This example specifies multiple .ws files. The command must be entered on one line.

ant -Dapproot=/home/myprojects/myapp
-Dwslocator='ld:MediatorTestDataServices/CustomerWeb.ws;
ld:MediatorTestDataServices/OtherCustomerWeb.ws' -f /home/bea/odsi_10.3/bin/
sdo_dspclientgen.xml

This example generates a JAR that includes all of the  .ws files in the dataspace. The command must be entered on line.

ant -Dapproot=/home/myprojects/myapp -Dwslocator=ALL -f /home/bea/
odsi_10.3/bin/sdo_dspclientgen.xml

10.3 Generating a Web Service Map and WSDL from a Data Service

If you intend to access a data service through web services using the Data Services Mediator API, you must generate a web service map file first. A web service map file maps data service functions to web service operations. The map file is also used for setting and configuring security policies for web services applications.

This section describes the following topics:

10.3.1 Creating a Map File

This section describes the basic steps that are required to create a map file. You can accomplish all of these tasks using the Oracle Data Service Integrator Eclipse IDE. The procedure assumes that you have created or have access to the data service (.ds) file from which you want to create a data service.

There are two ways to create a web service map file (.ws file):

Method 1

  1. Obtain access to the data space project containing the data service you wish to make accessible from a web service.

  2. Right-click on the data service name in Project Explorer and select Create Web Service Map. The map file (.ws file) is created with the same name as the data service file, and the map file is opened in the editor.

Method 2

  1. Obtain access to the data space project containing the data service you wish to make accessible from a web service.

  2. Right-click on the data service name in Project Explorer and select New > Web Service Map.

  3. Use the dialog to create an empty web service map file with a name of your choosing (example: OrderService).

  4. Click Finish. The empty map file opens in the editor.

  5. Drag either an entire data service file onto the map file or drag individual data service operations.

    Example: RetailApplication > OrderManagement > OrderService.ds

  6. Click OK. A file named OrderService.ws is created in the same folder as the source data service.

    Note:

    Only the data service functions that are mapped in the map file are available to clients. Only public data service operations can be mapped.

    Figure 10-1 shows a data service file called OrderService.ds as the source for a map file called OrderService.ws (created using Method 2).

    Figure 10-1 Adding a Data Service to a Web Services Map File

    Create Assembly wizard
    Description of "Figure 10-1 Adding a Data Service to a Web Services Map File"

    Note:

    You can add additional public operations from other data services to the same web service map file.

10.3.2 Generating a WSDL File from a Map File

To generate a WSDL file from a .WS file:

  1. Right-click on the .WS file.

  2. Choose Save WSDL As.

  3. Specify a name for the WSDL file.

  4. Click Save. Your new WSDL file should appear in the directory identified in the Save as dialog.

  5. Double-click on the WSDL file to verify the SOAP service for the WSDL.

    Note:

    A WSDL that has more than one schema section pointing to the same target namespace results in validation errors with the Eclipse WTP default WSDL validator. The WSDL generated in the above example is valid; however the project indicates a validation error condition.

    The error condition does not interfere with your ability to build and deploy the project. Also, you can use the following Eclipse option settings to prevent the validation error report from displaying:

    1. Select Project > Properties > Validation.

    2. Select Override validation preferences.

    3. Uncheck the Build option associated with the WSDL Validator.

    4. Click Apply, then OK.

    5. Select Project > Clean.

    6. Click OK.

      The validation error warnings should disappear.

10.3.3 Examining the Generated WSDL

You can examine the generated WSDL file. See Section 10.5, "Web Services Map File Reference" for details.

10.3.4 Testing the Generated WSDL

You can test the generated WSDL file. See Section 10.5, "Web Services Map File Reference" for details.

10.3.5 Modifying the Map File

This section describes additional ways to add data services and operation to a map, and how to delete operations from an existing map.

10.3.5.1 Adding Data Services and Operations

You can drag and drop either an entire data service or individual data service operations from the Project Explorer onto an existing map file in the map file editor.

You can right-click in the map editor and select Add Data Services/Operations to Map. Use the Select Resources to Add to Map dialog to add data service resources to the map.

10.3.5.2 Deleting Data Services and Operations from a Map File

To delete one or more operations, select the operations and right-click on the selected operations, and then select Delete.

To delete all operations that are related to a data service, right-click on the .ds dataservice box and select Delete.

10.3.5.3 Renaming Mapped Operations

To rename a mapped operation, select the operation, right-click and select Rename Operation. Then enter a new name for the mapped operation.

10.4 Configuring Security for Web Services Applications

This section describes the following topics:

Oracle Data Service Integrator Native Web Services supports the following security features:

  • Basic authentication (Web Application Security)

  • Transport level security (HTTPS)

  • Message level security (Web Services Security)

Note:

When configuring a BPEL process with SOAPReference, you must set oracle.soa.ws.outbout.omitWSA to true by updating the composite.xml file or using the Properties > Composite option. Then save the process and re-run the project.

10.4.1 Configuring Basic Authentication

To use basic authentication, set the Basic Auth Required property of the web services map file to true. For more information, see Section 10.5, "Web Services Map File Reference".

10.4.2 Configuring Transport Level Security (HTTPS)

Use the web service map file property editor to change the Transport Type to HTTPS. HTTP is the default. For more information, see Section 10.5, "Web Services Map File Reference".

For HTTPS, you can configure either 1-way or 2-way SSL. For detailed information on transport level security, see the Oracle WebLogic Server document Configuring Security: Configuring Transport-Level Security.

10.4.3 Configuring Web Services Security (WSS)

WSS provides message level security. For WSS, Oracle Data Service Integrator Native Web Services supports the same standards that are supported by Oracle WebLogic Server. For detailed information on WSS, see the Oracle WebLogic Server document, Configuring Security: Updating a Client Application to Invoke a Message-Secured Web Service.

The supported standards include:

  • SOAP Message Security

  • Username Token Profile

  • X.509 Certificate Token Profile

  • SAML Token Profile

To use Web Services Security with an Oracle Data Service Integrator web services application:

  1. Choose the type of web services security you want to use with your Oracle Data Service Integrator application.

  2. Configure security policies through the appropriate policy file(s). See the Oracle WebLogic Server document Configuring Security: Overview of Web Services Security for detailed information on configuring policy files for each type of web services security.

  3. Edit the web services mapping file to include your policy file(s). You can associate policies with an entire mapping file or for specific operations within the file. See Section 10.4.4, "Specifying Policies" for details.

10.4.4 Specifying Policies

You can specify policies for a map file or for individual operations in a map file.

10.4.4.1 Specifying Global Policies

To specify a policy for web services security for a map file:

  1. Create the policy file. See the Oracle WebLogic Server document WebLogic Web Services: Security for detailed information on configuring policy files for each type of web services security.

  2. Import the policy file into your Oracle Data Service Integrator project. The easiest way to do this is to use the IDE to import the file as a resource. The policy file must reside in the DSP-INF/policies directory.

  3. Configure the web services map file to include the policy.

The following listing shows an example .ws file that includes the optional, top-level policies element. Each policy element describes one policy file. The policies element can contain one or more policy elements. The locator attribute contains either an Oracle Data Service Integrator locator for the policy file or a fixed URI that describes the location of the standard WLS policy file.

Oracle Data Service Integrator supports three security policy types. Their URIs are: policy: Auth, policy: Encrypt, and policy: Sign. These are abstract policy files provided by Oracle WebLogic Server that describe authentication, encryption, and digital signature policies. These policy files do not have to physically reside in DSP project repository.

The policy element contains a required attribute Direction. This attribute represents at which direction the security policy will apply. The policy direction can be: REQUEST, RESPONSE, or REQUEST_RESPONSE.

  • REQUEST - The policy applies only to the inbound request message.

  • RESPONSE - The policy applies only to the response message.

  • REQUEST_RESPONSE - The policy applies to both inbound request and the response message.

Refer to the schema definition for detailed information on the structure of the map file (see Section 10.5, "Web Services Map File Reference").

Example 10-1 Sample Map File

<?xml version="1.0" encoding="UTF-8"?>
<web:WebServicesMap targetNamespace="ld:myMapper.ws" soapVersion="SOAP_1.1"
transportType="HTTP" ADODotNETEnabled="false" basicAuthRequired="false" xmlns:web="http://www.oracle.com/odsi/management/configuration/webservices/">
    <web:policies>
        <web:policy locator="ld:mypolicy.xml">
         <web:policy direction="REQUEST_RESPONSE">
    </web:policies>
    <web:dataServices>
        <web:dataService locator="ld:CUSTOMER.ds">
            <web:function name="deleteCUSTOMER" arity="1"
            operation="deleteCUSTOMER" returnInHeader="false">
                <web:parameterMapping>
                    <web:parameter name="p" wsdlMapping="SOAP_BODY"/>
                </web:parameterMapping>
            </web:function>
            <web:function name="updateCUSTOMER" arity="1"
            operation="updateCUSTOMER" returnInHeader="false">
                <web:parameterMapping>
                    <web:parameter name="p" wsdlMapping="SOAP_BODY"/>
                </web:parameterMapping>
            </web:function>
        </web:dataService>
    </web:dataServices>
</web:WebServicesMap>

10.4.4.2 Specifying Policies for a Function

To specify policies for a function in a map file:

  1. Follow the same basic instructions for specifying a policy for a web service map file, described previously.

  2. In the .ws file, add the policies element to the function element. The policies element contains one or more policy element. A policy element represents the security policy that applies to the WSDL operation. The optional child element ParameterMapping for the function element contains a list of parameters that are mapped to the SOAP header.

10.5 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 Section 10.3, "Generating a Web Service Map and WSDL from a Data Service."

This section describes the following topics:

10.5.1 Map File-Level Properties

The Oracle Data Service Integrator Eclipse IDE lets you create the web services map file (as explained in Section 10.3, "Generating a Web Service Map and WSDL 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.

Figure 10-2 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.

Figure 10-2 Map File-Level Properties

Create Assembly wizard
Description of "Figure 10-2 Map File-Level Properties"

Table 10-1 describes each of the map file properties.

Table 10-1 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 Section 10.4, "Configuring Security for Web Services Applications."

10.5.2 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.

Figure 10-3 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.

Figure 10-3 Operation-Level Properties

Create Assembly wizard
Description of "Figure 10-3 Operation-Level Properties"

Table 10-2 describes each of the operation properties.

Table 10-2 Operation 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

Specifies security policies that apply to the operation. For information on policies, see Section 10.4, "Configuring Security for Web Services Applications."

10.5.3 Map File XML Schema Definition

Example 10-1 is the schema file for the map (.ws file) definition.

Example 10-2 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>

10.5.4 Mapping of Data Service Type to WSDL Message Type

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

10.5.4.1 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.

Example 10-3 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>

10.5.4.2 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.

Example 10-4

<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>

10.5.4.3 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.

Example 10-5 Overloaded Functions

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

10.5.5 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.

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

  2. Choose View WSDL.

    The WSDL appears in its own window in the work area.

    Figure 10-4 View of Generated WSDL

    Create Assembly wizard
    Description of "Figure 10-4 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

10.5.6 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.

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

  2. Choose Test Web Service.

    The WSDL appears in its own window.

    Figure 10-5 View of Tested Web Service

    Create Assembly wizard
    Description of "Figure 10-5 View of Tested Web Service"

10.5.7 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.

10.6 Understanding SQL Maps

This section describes mapping functions in data services to SQL objects. It describes the following topics:

10.6.1 Overview

A SQL Map enables you to publish data service functions as SQL objects (which are created when you specify the mapping). Using SQL Maps, you can expose data services modeled in Oracle Data Service Integrator as relational data sources. This enables you to use reporting tools (such as Crystal Reports and Microsoft Access, among others), Java applications, and development tools (such as Data Tools Platform or SQL Explorer) to access information from data services using SQL queries (through a JDBC client).

Figure 10-6 Sample SQL Map

Create Assembly wizard
Description of "Figure 10-6 Sample SQL Map"

As Figure 10-7 shows, source data can be consolidated, integrated, and transformed using Oracle Data Service Integrator data services. The source data itself can come from disparate sources throughout the enterprise, including relational databases and web services, among others. Using SQL Maps you can, in turn, expose the data service operations as a relational data source accessible using SQL queries. This enables JDBC clients to access data consolidated through Oracle Data Service Integrator.

Figure 10-7 SQL Mapping Overview

Create Assembly wizard
Description of "Figure 10-7 SQL Mapping Overview"

You can publish the following types of data service artifacts for SQL access:

  • Data service functions, either with or without parameters.

  • External database functions. These are database-specific functions which are either built into a particular commercial database or which were custom-designed on the database side and then declared to Oracle Data Service Integrator as external database functions.

10.6.2 Publishable Operations

SQL mappable data service functions can be thought of as relationally-compatible XQuery functions. Depending on their signature, you can publish such functions for use as SQL tables or stored procedures. The association between the function and the SQL object is defined at design time when creating a SQL map.

The following summarizes the types of data service functions you can publish as SQL tables or stored procedures:

  • You can map non-parameterized data service functions as SQL tables, and parameterized data service functions as stored procedures.

  • You cannot map private or protected functions as part of a SQL Map.

  • You cannot map procedures as part of a SQL Map.

You can map library data service database functions to functions, but not to SQL tables and stored procedures.

Note:

See Section 10.8, "SQL Object Mapping Rules" for details about permitted mappings.

10.6.3 General Conditions

The following general conditions apply when exposing data service operations as relational data sources:

  • The exposed data service XQuery function signatures must only involve types that are supported by the relational (JDBC) type system.

  • The structure of the underlying schema (the Return type) must have a relationally-compatible data shape, which means that the data service type cannot include repeating data (data elements with cardinality greater than 1). This is because SQL provides a traditional, two-dimensional approach to data access, as opposed to the multi-level, non-normalized approach defined by XML.

    Note:

    For more information about creating data services with flat schemas, see Section 1.5.2, "Create a Data Service with a Flat Return Type."

  • You cannot map data service operations that return scalar (primitive) values as SQL tables or stored procedures.

10.7 Map Functions and Procedures to SQL Objects

This section describes how to create SQL objects (tables, stored procedures, and database functions) from dataspace project operations including conforming physical and logical functions and procedures. Once created, the objects will be available to client applications through JDBC.

10.7.1 Creating an SQL Map

To create an SQL map:

  1. In Eclipse for WebLogic, right-click a dataspace project folder in the Project Explorer and choose Add SQL Map. Eclipse for WebLogic creates an SQL Map with a default catalog and schema.

    Note:

    You can define only a single SQL Map for a dataspace. You can, however, add multiple catalogs and schemas to an SQL Map.

    You can rename the default catalog and schema by expanding the SQL Map in the Project Explorer, right-clicking the catalog or schema, choosing Rename, and entering the new name.

  2. Select the schema to which you want to map the data service functions and procedures. Eclipse for WebLogic displays folder tabs for Tables, Stored Procedures, and Functions.

  3. Drag-and-drop the data service functions and procedures from the Project Explorer to the corresponding folder tab in the SQL Map.

    If you drag-and-drop an entire data service to a folder tab in the SQL Map, Eclipse for WebLogic attempts to map all functions contained in the data service to the corresponding SQL object type (Table, Stored Procedure, or Function).

    Note:

    If you attempt to map a dataspace object which does not meet SQL map criteria, a dialog will appear, explaining the problem.

    You can map the same data service function or procedure to multiple schemas. You can also map a function or procedure to multiple SQL object types, however, Eclipse for WebLogic displays an alert dialog (see Map Data Service Functions for SQL Use Alert Dialog) in case of a naming conflict and suggests a new SQL name. You can edit this new name, as required.

    Figure 10-8 Populated SQL Map

    Create Assembly wizard
    Description of "Figure 10-8 Populated SQL Map"

10.7.2 Removing an SQL Map

To remove an SQL map, right-click the dataspace project folder and choose Remove SQL Map.

10.8 SQL Object Mapping Rules

The function and procedure types used in data services map to various types of SQL objects. The general mapping rules are described in Table 10-3.

Table 10-3 Mapping Rules

Type Element Type Optional Functions

Read functions

Yes

Yes

No

Navigation functions

Yes

Yes

No

Private functions

No

No

No

Protected functions

No

No

No

Procedures

No

No

No

Library data service functions (non-database)

Yes

Yes

No

Library data service database functions

No

No

Yes

10.9 Constraints on Publishing Data Service Objects to SQL

There are semantic and structural constraints to publishing data service objects to SQL.

Semantic constraints include some general types of objects as private functions.

Table 10-4 outlines the structural constraints on publishing data service artifacts to SQL.

Table 10-4 Structural Constraints

Limitation Discussion

Limitation affecting all SQL objects

Limitations in this section affect publication to any type of SQL object.

Functions referring to types that are neither simple nor elements

Examples of such types include item, node, and attribute.

Functions with anonymous element types

Functions containing elements where the name is not defined are not mapable. For example:

declare function f() as element()

Functions declarations using recursive XML types

For example, a function declaration with a complex type (PersonType) containing an element that is also of type PersonType is not mapable:

<element name="PERSON" type="tns:PersonType"/>
 
<complexType name="PersonType">
  <sequence>
    <element name="first_name" type="string"/>
    <element name="last_name" type="string"/>
    <element name="contact" type="tns:PersonType"/>
  </sequence>
</complexType>

XML types with content models containing wildcards

XML wildcards include:

• xs:any
• xs:anyAttribute

XML types with mixed content

 
<a>
  <child/>
  this is simply text
  <child/>
</a>

Limitations affecting publishing as a SQL Table

Limitations in this category affect publishing as SQL tables.

Functions with parameters

Functions with parameters can be mapped as stored procedures.

Functions containing simple return types

Functions containing simple return types can be mapped as SQL functions.

Functions containing any non-tabular element type

See Section 10.9.1, "Non-Tabular Element Types Affect Ability to Publish Functions as SQL Objects". Also applies to stored procedures.

Functions with any AtomicType types

Also applies to stored procedures.

Limitations affecting publishing as a stored procedure

Limitations in this category affect publishing as a stored procedure.

Functions accepting element parameter types

These functions cannot be published as stored procedures.

Functions containing a sequence of simple return types, such as xs:string*

The function declaration is not eligible. For example:

declare function f($p as xs:string*) as xs:int

Functions with anyAtomicType types

Also applies to tables.

Functions with any non-tabular element types

See Section 10.9.1, "Non-Tabular Element Types Affect Ability to Publish Functions as SQL Objects". Also applies to tables.

Limitations affecting publishing as a SQL Function

Limitations in this category affect publishing as a SQL functions.

Function with a sequence parameter type and an arity greater than 1.

An example shows xs:int* as the sequence parameter type:

declare function f($p as xs:int*, $q as xs:string) as xs:int

Functions with element types

 
declare function f ($p as element(e)) as xs:int

10.9.1 Non-Tabular Element Types Affect Ability to Publish Functions as SQL Objects

The structure of a data service function determines whether it can be mapped to an SQL object or not. For example, a parameterized function cannot be published as an SQL table since by definition SQL tables do not take parameters. Some structural constraints are practically self-evident; others are less obvious.

Note:

A quick way to determine if a particular function can be published to a particular type of SQL object is to drag the function to a SQL object table, stored procedure, or functions folder. Even if the function is grayed out — meaning that it cannot be published to any type of SQL object — an alert dialog will appear explaining why the selected object cannot be published.

For example, functions with non-tabular element types cannot be published as tables or stored procedures because XML output structure cannot be mapped to a normalized SQL table.

Underlying each data service is an XML type, or schema. Some XML types are readily mapped for JDBC use because they are — like SQL tables — two dimensional.

<CUSTOMER>
   <FIRST_NAME>
   <LAST_NAME>
   <CUSTOMER_ID>
</CUSTOMER>

When published as SQL, the table structure corresponds to the following:

FIRST_NAME    LAST_NAME    CUSTOMER_ID
Jack          Black        CUSTOMER1

As long as the object mapper can reduce the structure of the XML document to rank-one, the mapping can occur. For example:

<CUSTOMER>
   <FIRST_NAME>
   <LAST_NAME>
   <CUSTOMER_ID>
   <CUSTOMER_ORDER>
      <ORDER_ID>
      <C_ID>
      <ORDER_DT>
   </CUSTOMER_ORDER>
</CUSTOMER>

This is publishable as a table in the following form as long as there is one or fewer customer orders associated with the customer:

FIRST_NAME     LAST_NAME     CUSTOMER_ID     ORDER_ID     C_ID       ORDER_DT
Jack           Black          CUSTOMER1      ORDER_1_0    CUSTOMER1  2001-10-01

If, however, the CUSTOMER_ORDER type is unbounded, meaning that it can represent more than one order associated with a single customer, the structure no longer corresponds to a well-formed relational table and the mapping is not allowed.