Client Application Developer's Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Supporting ADO.NET Clients

This chapter describes how to enable interoperability between BEA AquaLogic Data Services Platform data services and ADO.NET client applications. With support for ADO.NET client applications, Microsoft Visual Basic and C# developers who are familiar with Microsoft's disconnected data model can leverage AquaLogic Data Services Platform data services as if they were ADO.NET Web services.

From the Microsoft ADO.NET developers' perspective, support is transparent: you need do nothing extraordinary to invoke functions on a AquaLogic Data Services Platform data service—all the work is done on the server-side. ADO.NET-client-application developers need only incorporate the AquaLogic Data Services Platform-generated WSDL into their programming environments, as you would when creating any Web service client application.

General information about how AquaLogic Data Services Platform achieves ADO.NET integration is provided in this chapter, as are the server-side operations required to enable it. The chapter includes the following sections:

Note: The details of ADO.NET development are described on Microsoft's MSDN Web site ( See that site for information about developing ADO.NET-enabled applications.


Overview of ADO.NET Integration in Data Services Platform

Functionally similar to service data objects (SDO), ADO.NET is data object technology for Microsoft ADO.NET client applications. ADO.NET provides a robust, hierarchical, data access component that enables client applications to work with data while disconnected from the data source. Developers creating data-centric client applications use C#, Visual Basic.NET, or other Microsoft .NET programming languages to instantiate local objects based on schema definitions.

These local objects, called DataSets, are used by the client application to add, change, or delete data before submitting to the server. Thus, ADO.NET client applications sort, search, filter, store pending changes, and navigate through hierarchical data using DataSets, in much the same way that SDOs are used by AquaLogic Data Services Platform client applications.

See Role of the Mediator and SDOs for more information about working with SDOs in a Java client application. Developing client applications to use ADO.NET DataSets is roughly analogous to the process of working with SDOs.

Although functionally similar on the surface, as you might expect with two dissimilar platforms (Java and .NET), the ADO.NET and SDO data models are not inherently interoperable. To meet this need, Data Services Platform provides ADO.NET-compliant DataSets so that ADO.NET client developers can leverage data services provided by Data Services Platform, just as they would any ADO.NET-specific data sources.

Enabling a Data Services Platform data service to support ADO.NET involves three key steps:

Understanding ADO.NET

ADO.NET is a set of libraries included in the Microsoft .NET Framework that help developers communicate from ADO.NET client applications to various data stores. The Microsoft ADO.NET libraries include classes for connecting to a data source, submitting queries, and processing results. The DataSet also includes several features that bridge the gap between traditional data access and XML development. Developers can work with XML data through traditional data access interfaces, and vice-versa.

Note: See Microsoft's MSDN site ( for more information about ADO.NET and client application development.

Although ADO.NET supports both connected (direct) and disconnected models, in Data Services Platform only the disconnected model is supported.

ADO.NET Client Application Development Tools

ADO.NET client applications are typically created using Microsoft Windows Forms, Web Forms, C#, or Visual Basic. Microsoft Windows Forms is a collection of classes used by client application developers to create graphical user interfaces for the Windows .NET managed environment. Web Forms provides similar client application infrastructure for creating Web based client applications. Any of these client tools can be used by developers to create applications that leverage ADO.NET for data sources.

Figure 9-1 ADO.NET Clients Supported via Web Services

ADO.NET Clients Supported via Web Services

Support for ADO.NET clients is provided via Web services, so before you can use your Microsoft tools of choice, you must perform the two basic tasks required for web-service client development, just as you normally would for any Microsoft Web services client application (see Figure 9-1):

Once the client-side artifacts have been incorporated into your development environment, you can invoke functions on the data service and manipulate the DataSet objects in your code as you normally would.

Note: The process of generating the WSDL and server-side artifacts is described in Generating a Web Service for ADO.NET Clients.

Understanding How AquaLogic Data Services Platform Supports ADO.NET Clients

BEA AquaLogic Data Services Platform supports ADO.NET at the data object level. That is, Data Services Platform maps inbound ADO.NET DataSet objects to SDO DataObjects, and maps outbound SDOs to DataSets. The mapping is performed transparently on the server, and is bidirectional.

Table 9-2 ADO.NET and SDO Data Objects Compared
Disconnected data models. Queries return results conforming to this data model.
Mechanisms for tracking changes made to data objects by a client application.

As shown in Figure 9-3, the ADO.NET typed DataSet is submitted to and returned by AquaLogic Data Services Platform. At runtime, when a Microsoft-.NET client application makes a SOAP invocation to the ADO.NET-enabled Web service, the Web service intercepts the object and passes it to the Data Service control.

The ADO.NET-enabled Data Service control is the linchpin of the interoperability between the two platforms. It comprises several wrapper classes—one for each typed DataSet—that are used to provide bidirectional mapping.

Figure 9-3 Data Services Platform and .NET Integration

Data Services Platform and .NET Integration

The required wrapper classes are created automatically, during the process of creating the ADO.NET-enabled Data Service control, as described later in this chapter. The wrapper classes are based on the XML schema file that gets generated during Data Service control creation.

At runtime, the ADO.NET-enabled Data Service control uses the wrapper classes to provide the ADO.NET client with the appropriate objects. The specifics vary, depending on the type of function or procedure:

As mentioned previously, mapping, transformation, and packaging processes are transparent to client application developers and data services developers. Only the items listed in Table 9-4 are exposed to data service developers.

Table 9-4 Data Services Platform—Java and ADO.NET-Enabled Artifacts
Data Service
An XQuery file that instantiates read functions, navigation functions, procedures, and update functionality at runtime.
Data Service Schema
The schema associated with the return type of the original data service.
DataSet Schema
The typed DataSet schema that conforms to Microsoft requirements for ADO.NET data objects.
Data Service Control
An ADO.NET-enabled data service control.
Web Service Source
A Java Web service that can intercept ADO.NET data objects and pass them to an ADO.NET-enabled Data Service control.
An automatically created folder for containing generated typed DataSet XSDs.
Web Service Definition
Generated WSDL that conforms to the ADO.NET typed DataSet schema.

Supporting Java Clients

The WSDL generated by the WebLogic Server from an ADO.NET-enabled Data Service control is specific for use by Microsoft ADO.NET clients. Exposing data services as Web services that are usable by Java clients is generally the same, although the actual steps (and the generated artifacts) are specific to Java. The steps are summarized in Table 9-5.

Table 9-5 Summary of Steps for Supporting Regular Clients
For more information...
Generate Data Service Control (regular, not ADO.NET-enabled)
Generate Web service file (JWS)
Generate WSDL


Enabling AquaLogic Data Services Platform Support for ADO.NET Clients

The process of providing ADO.NET clients with access to data services is a server-side operation that takes place in the context of an application and WebLogic Workshop.

The instructions in this section assume that you have created a data service application and that you want to provide access to the functions of the service to ADO.NET client applications. (For information about designing and developing data services, see the Data Services Developer's Guide.)

Enabling a AquaLogic Data Services Platform application to support ADO.NET clients is generally a three-step process:

The tasks described in the remaining sections assume that a data services application is open in WebLogic Workshop.

Creating a New Web Service Project

Since the ADO.NET support is accomplished through the use of Data Service controls, and since the Data Service controls require being exposed as Web services in order to make them network accessible, the first step is to create a Web service project and the folder structure necessary to hold generated components.

In the data service application that you want to ADO.NET-enable, create a new Web service project specifically for the ADO.NET-enabling components of the application (see Figure 9-6).

Note: Be sure to give the Web service project a meaningful name; the name will be used during the generation of several artifacts, including the name of the Data Service control.
Figure 9-6 Folder Structure for ADO.NET-Enabled Project Components

Folder Structure for ADO.NET-Enabled Project Components

Creating an ADO.NET-Enabled Data Service Control

Data Service controls can be ADO.NET-enabled simply by selecting the appropriate checkbox during the creation process. The ADO.NET-Enabled Data Service controls created (as described in this section) are designed exclusively to support ADO.NET clients through a Web services interface: such controls cannot be used in Page Flows, Portals, or other development scenarios.

Starting from the Web service project folder, here are the general steps:

  1. Create a folder in your project for the Data Service control by selecting a folder and right-clicking on that folder. (Java controls must be contained inside a folder within a project—they cannot reside at the top level of the project.)
  2. Right-click on the folder in the project to display the popup menu, and then select New Arrow symbol Java Control. The New Java Control dialog displays.
  3. Select Data Services Platform from the New Java Control dialog. Enter a filename for the control (JCX) file and click Next. The New Java Control - Data Service dialog displays.
  4. Enter the connection information for the WebLogic Server that hosts the Data Services Platform application.
    • For a local server, the Data Service control uses the connection information stored in the application properties.
    • For a remote server, you must select Remote and then provide the server URL, user name, and password.
  5. Click Create to continue. The Select Data Service Functions dialog displays. Note the ADO.NET-Enable checkbox in the upper-left-hand corner of the dialog, shown in Figure 9-7.
  6. Figure 9-7 Select Data Service Functions Dialog

    Select Data Service Functions Dialog

  7. Click the ADO.NET-enabled box and then select one or more functions or procedures to use in the ADO.NET-enabled data service control.
  8. Note: Due to a Microsoft limitation, the functions and procedures that you add to your Data Service control must belong to the same namespace.
  9. Click Next to continue. A Control generation detailed configuration page displays, showing the functions select on the previous page. On this page, you can select the functions (if any) that should include a filter or an attribute.
  10. Click Finish to complete the process.

As the ADO.NET-enabled Data Service control file is being generated, a folder is also created inside the controls folder, and a Microsoft-style XML schema definition file (XSD) is generated and placed inside the folder. The generated folder follows this simple naming convention:

<Data Service control name>_schema

The schema file created in the <Data Service control name>_schema folder is a combination of the Data Service control name and "DataSet;" for example, CustomerDataSet.xsd. (See Table 9-4 for other relevant naming conventions.) The XML schema file contains method calls for all selected functions and procedures.

As the XSD is created, you may see a Message box display briefly in WebLogic Workshop, notifying you that you have added one or more XSD files to a non-Schema project. Such a message can be disregarded; it is raised because the Microsoft ADO.NET style XSD is not the same as other data service XSD files.

Note: For more information about Data Service controls, see Creating Data Service Controls.

Java controls are not network-addressable unless wrapped as Web services. Invoking a Java Control of any kind, including a Data Service control from outside the application, requires that it be exposed as a Web service or as another Web-based application, such as a JSP (JavaServer Page).

Note: Deleting a JCX does not cause the deletion of any associated schema (XSD) files. Instead if you need to remove these files from your system, do so manually.

Generating a Web Service for ADO.NET Clients

After the ADO.NET-enabled Data Service control has been generated, it is used as the basis for generating a Java Web service file (JWS), as follows:

  1. Right-click on the Data Service control.
  2. Select Generate Test JWS File (Stateless) from the pop-up menu. (ADO.NET client support is limited to stateless Web services.)

Shortly, the JWS is generated; you will see it displayed as a node under the Data Service control. From this JWS you can now generate the companion WSDL (Web Services Description Language) file that will be used by Web service client-application developers.

Note: After the Java Web service (JWS) file has been generated, it can be deployed in the usual manner. See the Web services page on BEA's documentation site for more information:

Generating an ADO.NET-Enabled WSDL

To generate the companion WSDL (Web Services Description Language) file from the JWS that can be used by Web service clients to invoke operations on the ADO.NET-enabled Web service:

  1. Right-click on the JWS file created in Generating a Web Service for ADO.NET Clients.
  2. Select Generate ADO.NET Enabled WSDL File from the pop-up menu.

In a moment, the WSDL is generated; you will see it displayed as a node under the JWS file.

Figure 9-8 Generated WSDL in WebLogic Workshop

Generated WSDL in WebLogic Workshop

Note: The building of RPC-style Web services on top of AquaLogic Data Services Platform controls is not supported. For this reason RPC-style Web services built on cannot be created from ADO.NET clients utilizing AquaLogic Data Services Platform.

The WSDL should be made available to ADO.NET developers directly (for example, by sending the physical file to them). Developers can also obtain the WSDL from the BEA WebLogic Server's home page.


Adapting AquaLogic Data Services Platform XML Types (Schemas) for ADO.NET Clients

Fundamentally, Microsoft's ADO.NET DataSet is designed to provide data access to a data source that is — or appears very much like — a database table (columns and rows). Although, later adapted for consumption of Web services, ADO.NET imposes many design restrictions on the Web service data source schemas.

Due to these restrictions, Data Services Platform XML types (also called schemas or XSD files) that work fine with data services may not be acceptable to ADO.NET's DataSet.

This section explains how you can prepare XML types for consumption by ADO.NET clients. It covers both read and update from the ADO.NET client side to the AquaLogic Data Services Platform server, specifically explaining how to:

Note: See the Data Services Developer's Guide for detailed information related to creating and working with XML types.

Approaches to Adapting XML Types for ADO.NET

There are several approaches to adapting XML types for use with an ADO.NET DataSet:

XML Type Requirements for Working With ADO.NET DataSets

The following guidelines are provided to help you develop ADO.NET DataSet-compatible XML types (schemas) by providing pattern requirements for various data service artifacts.

Requirements for Complex Types

Requirements for supporting a complex type in an ADO.NET DataSet include:

Requirements for Recurring References

Since ADO.NET does not support true recurring references among complex types, the requirements noted in Requirements for Complex Types should be followed when simulating schema definitions utilizing such constructs as:

As an example, if an address complex type has been referenced by both Company and Department, there should be two element definitions, CompanyAddress and DepartmentAddress, each with an anonymous complex type. The following code illustrates this:

<xsd:schema targetNamespace="urn:company.xsd" xmlns:xsd="">

<xsd:element name="Company">
  <xsd:element name="Name" type="xsd:string"/>
  <xsd:element name="CompanyAddress">
     <xsd:element name="City" type="xsd:string"/>
   <xsd:element name="Department">
      <xsd:element name="Name" type="xsd:string"/>
      <xsd:element name="DepartmentAddress">
         <xsd:element name="City" type="xsd:string"/>
Requirements for Simple Types

Requirements for supporting simple types in an ADO.NET DataSet include:

Requirements for Target Namespace and Namespace Qualification

Requirements for using target namespaces and namespace qualification include:


Further information regarding XML schemas can be found at:


Generated Artifacts Reference

The process of creating a ADO.NET-enabled Data Service control and Web service generates two ADO.NET-specific artifacts:

Technical specifications for these artifacts are included in this section.

XML Schema Definition for ADO.NET Typed DataSet

During the process of creating a ADO.NET-enabled data service control, WebLogic Workshop generates a special schema file that conforms to Microsoft's specifications for typed DataSet objects. A schema is generated for each data service query that has been selected for inclusion in the ADO.NET-enabled data service control. These schema files take the name of the source schema's root element.

In the generated schema, the root element has the IsDataSet attribute (qualified with the Microsoft namespace alias, msdata) set to True, as in:


In keeping with Microsoft's requirements for ADO.NET artifacts, the generated target schema of the data service and all schemas on which it depends are contained in the same file as the schema of the typed DataSet. As you select functions to add to the control, WebLogic Workshop obtains the associated schemas and copies the content into the schema file.

In addition, the generated schema includes:

Listing 9-1 shows an excerpt of a schema—CustomerDS.xsd—for a typed DataSet generated from a AquaLogic Data Services Platform Customer schema.

Listing 9-1 Example of a Typed DataSet (ADO.NET) Schema
<xs:schema xmlns:mstns="" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns="" targetNamespace="" id="CustomerDS" xmlns:xs="">
  <xs:element msdata:IsDataSet="true" name="CustomerDS">
      <xs:choice maxOccurs="unbounded"> 
        <xs:element ref="CUSTOMER"/>
<xs:element name="CUSTOMER">
. . .

Web Services Description Language (WSDL) File for Microsoft ADO.NET Clients

The process of generating the Java Web service produces a WSDL for the client-side application development. The WSDL file contains import statements that correspond to each typed DataSet. Each of the import statements is qualified with the namespace of its associated DataSet schema, as in this example:

<import namespace="" location="LDTest1NET/CustomerDataSet.xsd"/>

In addition, the WSDL includes the ADO.NET compliant wrapper type definitions. The wrappers' type definitions comprise complex types that contain sequences of any type element from the same namespace as the typed DataSet, as in:

<s:complexType name="CustomerDataSetWrapper">
<s:any namespace=""/>

  Back to Top       Previous  Next