13 Importing and Publishing Web Services

In Oracle Warehouse Builder, you can publish core functions such as mappings as a Web service. The Web service can then be imported by other applications. Similarly, you can import Web services published by other applications into Oracle Warehouse Builder. Publishing Oracle Warehouse Builder functions as Web services enhances their visibility and makes them accessible to a larger number of applications because these Web services are created using widely accepted open standards based on XML.

This chapter contains the following topics:

"Defining Web Services"
"Publishing Functions as Web Services"
"Importing External Web Services"

Defining Web Services

Web services are application components that use XML-based open standards to define how data in an application can be accessed by different clients. These clients may be working on different platforms and residing on different networks. When seen as a Client-Server model, a Web service resides on a server and clients use transport protocols to retrieve the Web service from the server.

Web service data is packaged as messages whose format is defined by the Simple Object Access Protocol (SOAP) framework. SOAP is a transport protocol for transmitting XML-based messages over a network. It generally uses HTTP for transmission. Any client that can read and interpret SOAP- based messages can thus access data from a Web service. Oracle Warehouse Builder supports SOAP versions 1.1 and 1.2.

A Web service is built using Web Services Description Language (WSDL). A WSDL file is an XML file that describes a Web service and provides details of how to communicate using the Web service. It provides details of the transport protocols and the message format that the Web service uses. The file also contains details of the port, which is a metatag in the WSDL file, that defines the operations or functions of a Web service. Oracle Warehouse Builder supports WSDL version 1.1.

An example of a WSDL file that defines a Web service is as shown:

<definitions
     name="PfWebServiceImplService"
     targetNamespace="http://oracle.wh.jrt.sdk.packaging.dbWebService/"
     ............................
    >
    <types>
    </types>
    <message name="runInput"/>
    <message name="runOutput">
        <part name="return" type="xsd:int"/>
    </message>
    .........................
    <portType name="PfWebServiceImpl">
        <operation name="run">
            <input message="tns:runInput" xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl"
                 ns1:Action=""/>
            <output message="tns:runOutput" xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl"
                 ns1:Action=""/>
        </operation>
        ................................
    </portType>
    <binding name="PfWebServiceImplSoapHttp" type="tns:PfWebServiceImpl">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="run">
            <soap:operation soapAction=""/>
            <input>
                <soap:body use="literal" namespace="http://oracle.wh.jrt.sdk.packaging.dbWebService/"/>
            </input>
            <output>
                <soap:body use="literal" namespace="http://oracle.wh.jrt.sdk.packaging.dbWebService/"
                     parts="return"/>
            </output>
        </operation>
        .............................
    </binding>
    <service name="PfWebServiceImplService">
        <port name="HttpSoap11" binding="tns:PfWebServiceImplSoapHttp">
            <soap:address location="REPLACE_WITH_ACTUAL_URL"/>
        </port>
    </service>
</definitions>

The WSDL file is automatically generated by Oracle Warehouse Builder when you publish a Web service. The function of the Web service is defined within the portType metatag. The soap:address location metatag defines the location where the Web service is deployed.

Publishing Functions as Web Services

Publishing Oracle Warehouse Builder functions as Web services ensures that these functionalities are widely available to clients that use the same XML-based open standards. The following functionalities can be published as Web service:

Mappings (Code template-based mappings and non code template-based mappings)
Process Flows
Transformations (Functions, Procedures, Packages)
Data Auditors
Modules and Tables

Note:

You can publish only those tables and modules that are imported through native database connection. The modules must have a Change Data Capture code template associated with them. The tables must be identified as being tracked for CDC.

Operations and Parameters Generated in a Web Service

There are three types of parameters that can be passed on to a Web service when it is executed.

Custom parameters (custom_params): These are input parameters that you might have to enter while executing Web services that are based on PL/SQL mappings, process flows, and data auditors. For example, if you create a Web service based on a mapping that requires you to enter input parameters, then you must provide the input through custom parameters while executing the Web service.
System parameters (system_params): These are parameters that you can configure for an object in Oracle Warehouse Builder. For example, for a mapping, you can configure its runtime parameters, such as Bulk Size, Audit Level, and so on. These values are then passed on as system parameters while executing a Web service based on the mapping. System parameters are applicable to Web services based on PLS/SQL mappings, process flows, and data auditors.
OWB parameters (owb_params): These parameters are used in Web services that are based on code template mappings and CDC objects, as these objects are executed in a control center agent.

See Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide for more information about the different parameters.

For each of the objects that can be published as a Web service, the following operations and parameters are generated in a Web service.

Non Code Template Mappings, Process Flows, and Data Auditors: You can use the following operations.
- run(): Run the Web service without any parameters.
- runWithSystemParam(string system_params): Run the Web service with system parameters.
- runWithCustomParam(string custom_params): Run the Web service with custom parameters.
- runWithParams(string system_params, string custom_params, boolean isAsync): Run the Web service with system and custom parameters. If the Async value is set to true, then the process is run in the background.
Code Template Mappings: You can use the following operations.
- runWithoutParams(): Run the Web service without any parameters.
- runWithOwbParams(string owb_params): Run the Web service with Oracle Warehouse Builder parameters.
The format to specify a parameter is PARAM=x. Multiple parameters are separated by comma. For example, the system parameters for a mapping can be specified as:
```
OPERATING_MODE=SET_BASED,AUDIT_LEVEL=NONE
```
Note:
When you publish a code template-based mapping as a Web service, the code for the mapping is embedded within the Web service. Therefore, when you make changes to such mappings, you must redeploy the Web service.
However, when you publish non code template-based mappings, such as PL/SQL mappings, as a Web service, the code for the mapping is not embedded within the Web service. Instead, the Web service contains only a reference to the code. Therefore, when you make changes to the mapping, you must redeploy only the mapping. You do not have to redeploy the Web service.
Transformations: For Web services based on transformation operators, the operations are the same as those for the function, which means that they share the same function name and parameters.
Modules and Tables (CDC based): Consistent set CDC uses the following module commands:
- start_cdc(): Set up the CDC infrastructure.
- drop_cdc(): Remove the CDC infrastructure.
- subscribe(string subscriber_name): Add a subscriber to this CDC.
- unsubscribe(string subscriber_name): Remove a subscriber from the CDC.
- extend_window(): The Consistency Window is a range of available changes in all the tables of the consistency set for which insert, update, delete are possible without violating referential integrity. The extend window operation computes this window to consider new changes captured since the latest Extend Window operation.
- lock_subscriber(string subscriber_names): Although the extend window is applied to the entire consistency set, subscribers consume the changes separately. This operation performs a subscriber(s) specific snapshot of the changes in the consistency window. This snapshot includes all the changes within the consistency window that have not been consumed yet by the subscriber(s).
- unlock_subscriber(string subscriber_names): This operation commits the use of the changes that were locked during the lock subscriber operations for the subscribers. It should be processed only after all the changes for the subscribers have been processed.
- purge_cdc(): After all subscribers have consumed the changes they have subscribed to, extra entries may still remain in the Capture tables and must be deleted. This is performed by the Purge Journal operation.

For non-consistent set CDC, Start, Drop, Subscribe, and Unsubscribe commands are available for both tables and modules. Lock Subscriber and Unlock Subscriber are available but not used.

Creating a Web Service

Web services are stored in Application Server modules. Creating a Web service involves the following tasks:

"Creating an Application Server Module"
"Providing an Application Server Location"
"Creating the Web Service"

Creating an Application Server Module

Web services are created under Application Server modules. To create an Application Server Module:

In the Projects Navigator, right-click Application Servers and click New Application Server.

The Create Module Wizard is displayed.
Click Next to proceed to the Name and Description page. Provide a name, and description (optional).
Click Next to proceed to the Connection Information page. Provide the location details, as described in "Providing an Application Server Location" .
Click Next, and on the Summary page, click Finish after verifying the details.

The newly created module is now available under the Application Servers node. It consists of two sub-nodes: Web Services and Web Service Packages.

Application Server Modules can also be created under Public Application Servers from the Globals Navigator.

Providing an Application Server Location

You can provide the location information while creating an Application Server module or while deploying a Web service.

A Web service can be deployed to the following locations:

OC4J Standalone
Oracle Application Server

Before providing the location information, ensure that the control center agent (CCA) is running. See "Starting and Stopping the Control Center Agent" for more information about starting and stopping a control center agent on Windows and UNIX systems.

To create a location:

On the Connection Information page, click Edit to open the Edit Agent Location dialog box and provide the following details:
- Username: The oc4jadmin user or application server user with sufficient privileges.
- Password: Password set for oc4jadmin user while running ccastart file.
- Host: The host where OC4J or the application server resides.
- Port: The port number to access the server. The default value is 23791.
- Port Type: RMI Port for OC4J Standalone, OPMN for Oracle Application Server.
- Instance: OC4J instance name. To be provided only for Oracle Application Server.
- Application Name: The default value is set to jrt.
- HTTP Port: This port is used if the Web service is accessed through a browser. The default value is set to 8888.
Click Test Connection to verify the connection details.

You cannot deploy a Web service without providing a valid deployment location. If you try to deploy a Web service without providing the deployment location, Oracle Warehouse Builder displays the Edit Agent Location dialog box. Provide the connection details before attempting to deploy the Web service.

Creating the Web Service

Within the Application Server module, you can create a standalone Web service or create a Web service under a Web Service Package.

To create a Web Service Package:

Right-click Web Services Packages and click New Web Service Package.

The Create Web Service Package dialog box is displayed.
Provide a name and a description (optional), and click OK.

The newly created Web service package is now available under the Web Services Package node.

If you selected the Proceed to Web Service Wizard option, the Create Web Service Wizard is displayed and you can create individual Web services.

To create a Web service:

Right-click Web Services and click New Web Service.

The Create Web Service Wizard is displayed.
Click Next to proceed to the Name and Description page. Provide a name and description (optional).
Click Next to proceed to the Define Implementation page. Select the object is to be published as a Web service.
Click Next to proceed to the Review Specification page.

Click View Source to view the WSDL file that is generated for the Web service.
Click Finish to create the Web service.

The newly created Web service is now available under the Web Services node.

Importing External Web Services

You can import Web services using the Public Application Servers node, which is available in the Globals Navigator.

To import a Web service, you must first create an application server module and then import the Web service into this module.

To create an Application Server module:

On the Globals Navigator, right-click Public Application Servers and select New Application Server.

The Create Module dialog box is displayed.
Provide a name for the module.

The newly created module is now available under the Public Application Servers node.

To import a Web service:

Right-click the Application Server node and select New Web Service.

The Create Web Service wizard is displayed.
On the Name and Description page, provide the location details of the Web service.

You can import a Web service that is deployed to a local system. You can provide the location details using the URL format or browse for the location.

After importing a Web service, you can execute it to run its function. See Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide for more information about executing Web services.

See Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide for more information about creating, publishing, and executing Web services.