Data Services are specialized Web Services that provide access to data in datastores, and to captured changes in these datastores. These Web Services are automatically generated by Oracle Data Integrator and deployed to a Web Services container - normally a Java application server.
In the examples below, Apache Tomcat 5.5 or Oracle Container for Java (OC4J) are used as the application server, with Apache Axis2 as the Web Services container. These examples may need to be adapted if using other Web Services containers.
Setting up Data Services involves the following stages :
Setting up datastores in a Web Services container.
Configuring the topology to declare the Web Services container.
Setting up the model, to declare datastores and columns for Data Services.
Before getting started, you should already have configured your Web Services container and the application server. Refer to the respective documentation for these components for details.
The Data Services generated by Oracle Data Integrator do not contain connection information for sources and targets. Instead, they make use of datasources defined within the Web Services container or on the application server. These datasources contain connection properties required to access data, and must correspond to data servers already defined within the Oracle Data Integrator topology.
In addition, all necessary drivers for the specified datasources must be installed on the application server.
To set up a datasource:
Install the driver files (.jar or .zip) for your datasource in the appropriate directory for your application server. Use /common/lib for Tomcat. Use ORACLE_HOME/j2ee/home/applib for OC4J.
Create the JDBC Datasource pointing to the data server you want to access:
For Tomcat, Define the datasource and connection
properties for your data in the file WEB-INF/context.xml
on your Web Services container. Note the name of the resource (marked
in green below), as you will need
it later. Some connection properties can be found in the topology; these
are marked in blue.
One example is given below.
<Context >
<Resource
name="jdbc/Oracle_SRV1/Oracle/dataServices"
type="javax.sql.DataSource"
driverClassName="oracle.jdbc.OracleDriver"
url="jdbc:oracle:thin:@SRV1:1521:ORA10"
username="ODI"
password="ODI"
maxIdle="2"
maxWait="-1"
maxActive="4"/>
</Context>
For OC4J, you must define the datasource as follows:
Connect to OC4J administration interface.
In the Administration tab, in Services | JDBC Resources click Go to task.
Click the Create button in the Connection Pools section.
Select the Axis2 application, select New Connection Pool , then Continue.
Fill in the fields for the JDBC datasource then click Finish.
Click the Create button in the Data Sources section.
Select the Axis2 application, select Managed Datasource , then Continue.
Fill in the fields for the JDBC datasource
then click Finish.
For more information on configuring datasources for OC4J, refer
to the application server documentation.
Make a reference to the datasource in your Web
Services container's WEB-INF/web.xml file. Note
that you must specify the name of the datasource in the res-ref-name
tag.
One example of referencing the datasources defined above is given below:
...
<resource-ref>
<description>Data Integrator Data Services on Oracle_SRV1</description>
<res-ref-name>jdbc/Oracle_SRV1/Oracle/dataServices</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
Restart your Axis2 application to take the new datasources into account.
Once the Web Services container is ready, you must declare it as a data server in the topology, in order to let Oracle Data Integrator deploy Data Services on it.
Note : Be careful not to confuse the Web Services containers and the servers containing deployed data. While both are declared as data servers in Oracle Data Integrator, the former do not contain any data, and only serve to host the published Data Services.
Web Services containers declared in Oracle Data Integrator have one of three modes of deploying Web Services:
Copying files directly onto the server, if you have file access to the server.
Uploading onto the server by FTP.
Uploading with the Web Service Upload method supported on some servers, such as Axis2.
The next steps in the configuration of the Web Services container depend on the deployment mode you choose to use.
To configure the Web Services container:
In Topology Manager's Physical Architecture view, select the Axis2 technology. Right-click and select Insert Dataserver. If you are using a different Web Services container, then choose the appropriate technology instead.
Name: Name of the dataserver as it will appear in Oracle Data Integrator.
Base URL for published services: http://<Host>:<HTTP port>/axis2/services
Select the option corresponding to the chosen method of deployment:
File copy: Specify the directory in the application server which will receive Web Services.
Web Service Upload: Specify the root URL for the Axis2 application, typically http://<Host>:<HTTP port>/axis2/axis2-admin/, as well as the user name and password of the Axis2 administrator.
FTP Upload: Specify the FTP URL of the deployment directory as well as the user name and password of a user with rights to write in this directory.
Click OK.
A window will open to allow you to create a physical schema.
Go to the Context tab, and define one logical schema for each context in which you will deploy the Data Services.
Click OK.
Note : You only need to define one physical schema per Web Services container.
For further information about setting up the topology, refer to Creating the Topology.
To configure Data Services for a model, make sure that the datastores which you wish to deploy are already correctly defined (such as by reverse-engineering) and accessible. For further information, see Creating and Reverse-engineering a Model.
Make sure that you have imported the appropriate Service Knowledge Module (SKM) into one of your projects. The SKM contains the code template from which the Data Services will be generated. For further information on importing KMs, see Importing a KM.
You may also wish to consult the section Overview of Generated Services for further information about how the properties below will affect the generated Data Services.
To set up a model to use Data Services:
Open the model and go to the Services tab.
On the Application Server tab, select the Web Services container that you set up earlier.
Set the Namespace, which will be used in the generated WSDL.
Specify the Package name, used to name the generated Java package that contains your Web Service. Generally, this is of the form com.<company name>.<project name>
In the Datasource name field, copy/paste the name of the datasource that you defined for the server when setting up the datasources. This name should be prefixed by java:/comp/env/.
Define the Data Service Name. Note that this name is only used for the Data Service operating at the model level. You can also define a Data Service name for each datastore - see below.
Select a service knowledge module (SKM) from the list, and set its options. Refer to the description of the SKM for more information. Note that only those SKMs imported into projects appear here.
Go to the Deployed Datastores tab.
Select every datastore that you wish to expose as a Web Service. For each one, specify a Data Service Name and the name of the Published Entity.
Click OK to save your changes.
Although not required at first, you can also fine-tune the configuration of your generated Data Services at the datastore and column level.
To configure options for Data Services at the datastore level:
Open the datastore and select the Services tab.
Check Deploy as Data Service if you want the datastore to be deployed.
Enter the Data Service Name and the name of the Published Entity for the datastore.
Click OK to save your changes.
To configure Data Service options at the column level:
You can specify the operations that will be permitted for each column. One important use of this is to lock a column against being written to via Data Services.
Open the column and select the Services tab.
Check the operations that you wish to allow: INSERT, UPDATE, SELECT.
Click OK to save your changes.
Generating Data Services for a model also has the effect of generating the Data Services for the individual datastores.
To generate Data Services for a datastore or model:
Select the model or datastore for which you wish to generate the Data Services.
Right-click, and select Generate
Service.
The generation configuration window opens.
Specify the path to store the generated Data Service in. Oracle Data Integrator places the generated source code and the compiled Web Service here. This directory is a temporary location that can be deleted after generation.
Specify the Context. Note that the choice of context has three effects:
Determining the JDBC/Java datatype bindings at generation time.
Determining which physical schemas are used to provide data.
Determining which physical Web Services container is deployed to.
Choose 1 or more Generation phases. For normal deployment, all three phases should be selected. However, it may be useful to only perform the generation phase when testing new SKMs, for instance. See below for the meaning of these phases.
It is also possible to use the Generate and deploy... button on the Services tab in either the Datastore or Model window.
Note: Generating Data Services for a model generates one Data Service for the model, and an additional Data Service for each of the datastores which are enabled for publishing as such.
|
Phase |
Description |
|---|---|
|
Generation |
|
|
Compilation |
|
|
Deployment |
|
Data Services are only generated at the model-level when the model is enabled for consistent set CDC. The following services are generated:
extendWindow (no parameters): Carries out an extend window operation.
lock (SubscriberName): Locks the consistent set for the named subscriber. To lock the consistent set for several subscribers, call the service several times, using several SnpsInvokeWebService steps for example.
unlock (SubscriberName): Unlocks the consistent set for the named subscriber.
purge (no parameters): Purges consumed changes.
See Change Data Capture for more information on these operations.
The range of operations offered by each generated Data Service depends on the SKM used to generate it. There are several common properties shared by the SKMs currently supplied by Oracle Data Integrator. In almost every case the name of the published entity forms part of the name of each operation. In the following examples, the published entity "Customer" will be used.
Operations on a single
entity. These operations allow a single record to be manipulated, by specifying
a value for its primary key. Other fields may have to be supplied to describe
the new row, if any.
Examples: addcustomer, getcustomer,
deletecustomer, updatecustomer.
Operations on a group of entities specified by
filter. These operations involve
specifying values for one or several fields to define a filter, then optionally
supplying other values for the changes to made to those rows. In general,
a maximum number of rows to return can also be specified.
Examples: getcustomerfilter, deletecustomerfilter,
updatecustomerfilter.
The easiest way to test generated Data Services is to use the graphical interface for the SnpsInvokeWebService Oracle Data Integrator tool. See also Invoking a Web Service for more information.