Skip navigation.
Downloads | Product Documentation | Support

Client Application Developer's Guide

# Supporting ADO.NET Clients

This chapter describes how to enable interoperability between BEA AquaLogic Data Services Platform (DSP) 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 DSP 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 DSP data service—all the work is done on the server-side. ADO.NET-client-application developers need only incorporate the DSP-generated WSDL into their programming environments, as you would when creating any Web service client application.

General information about how DSP 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:

- Overview of ADO.NET Integration in Data Services Platform
- Enabling DSP Support for ADO.NET Clients
- Adapting DSP XML Types (Schemas) for ADO.NET Clients
- Generated Artifacts Reference

Note: The details of ADO.NET development are described on Microsoft's MSDN Web site (http://msdn.microsoft.com). 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 DSP 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:

- Creating an ADO.NET-Enabled Data Service Control (Note that ADO.NET-Enabled Data Service controls are intended exclusively to provide support to ADO.NET clients via a Web service interface, as described in this chapter: such controls cannot be used in Page Flows, Portals, or other development scenarios.)
- Generating a Web Service for ADO.NET Clients
- Generating an ADO.NET-Enabled WSDL

These steps are described in Enabling DSP Support for ADO.NET Clients.

## 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 (`http://msdn.microsoft.com/`) 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 6-1 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 6-1):

- Obtain the WSDL for the DSP Web service application.
- Generate the client side artifacts from the WSDL as required for the client application development tool you are using.

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 DSP 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 6-2 ADO.NET and SDO Data Objects Compared

ADO.NET | SDO | Description
--- | --- | ---
DataSet | DataObject | Disconnected data models. Queries return results conforming to this data model.
DiffGram | ChangeSummary | Mechanisms for tracking changes made to data objects by a client application.

As shown in Figure 6-3, the ADO.NET typed DataSet is submitted to and returned by DSP. 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 6-3 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:

- Functions. The Data Service control wraps a query result using the typed DataSet schema, adds the DataSet schema type to the result, and returns to the client.
- Procedures. A DSP procedure can return an SDO; another data type; or nothing (void). The Data Service control uses the wrapper classes as required, but only if required.
- Submitting changes. The Data Service control transforms an ADO.NET DataSet DiffGram to an SDO ChangeSummary, and then submits it to SDO Mediator. All submit methods take the corresponding wrapper classes as arguments.

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

Table 6-4 Data Services Platform—Java and ADO.NET-Enabled Artifacts

Name | Example | Description
--- | --- | ---
> Data Service |
>     Customer.ds
| An XQuery file that instantiates read functions, navigation functions, procedures, and update functionality at runtime.
> Data Service Schema |
>     Customer.xsd
| The schema associated with the return type of the original data service.
> DataSet Schema |
>     CustomerDataSet.xsd
| The typed DataSet schema that conforms to Microsoft requirements for ADO.NET data objects.
> Data Service Control |
>     Customer.jcx
| An ADO.NET-enabled data service control.
> Web Service Source |
>     Customer.jws
| A Java Web service that can intercept ADO.NET data objects and pass them to an ADO.NET-enabled Data Service control.
> <DSControlName>_schema |
>     Customer_schema
| An automatically created folder for containing generated typed DataSet XSDs.
> Web Service Definition |
>     CustomerNET.wsdl
| 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 6-5.

Table 6-5 Summary of Steps for Supporting Regular Clients

####

Task | For more information...
--- | ---
Generate Data Service Control (regular, not ADO.NET-enabled) | Creating Data Service Controls
Generate Web service file (JWS) | Server-side DSP-Enabled Web Service Development
Generate WSDL | Server-side DSP-Enabled Web Service Development

# Enabling DSP 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 DSP application to support ADO.NET clients is generally a three-step process:

- Creating an ADO.NET-Enabled Data Service Control
- Generating a Web Service for ADO.NET Clients
- Generating an ADO.NET-Enabled WSDL

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 6-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 6-6 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 —> 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 6-7.

Figure 6-7 Select Data Service Functions Dialog

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

Note: Due to a Microsoft limitation, the functions and procedures that you add to your Data Service control must belong to the same namespace.

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

- Add a filter to the JCX method (For more information about filters, see Filtering, Sorting, and Fine-tuning Query Results.)
- Add an attribute to the method.

8. 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 6-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).

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

`http://e-docs.bea.com/wls/docs81/webservices.html`

## 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 6-8 Generated WSDL in WebLogic Workshop

- See Web Services Description Language (WSDL) File for Microsoft ADO.NET Clients for information about the format of the WSDL.

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 Web service, from BEA WebLogic Server's home page.

# Adapting DSP 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 DSP server, specifically explaining how to:

- Read a DSP query result as a ADO.NET DataSet via SDO (since query results are presented as SDO DataObjects within DSP).
- Update DSP data sources using an ADO.NET DataSet's diffgram that is mapped to a SDO ChangeSummary.

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:

- Develop ADO.NET-compatible data services above the physical data service layer. You can develop data services on top of physical data sources that are specifically intended to be consumed by ADO.NET clients. (Details are described in XML Type Requirements for Working With ADO.NET DataSets.)

Note: Any ADO.NET-compatible data service XML types can be consumed by non-ADO.NET clients.

- Develop ADO.NET-compatible data services above a logical data service layer. If existing logical data services that are not ADO.NET-compatible must be reused, you can build an additional layer of ADO.NET-compatible data services on top of the logical data services.

Note: This approach may increase the likelihood of having to work with inverse functions and custom updates. (The usage of inverse functions is described in "Best Practices and Advanced Topics", Data Services Developer's Guide.)

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

- Defining the entire XML type in a single schema definition file. This means not using include, import, or redefine statements.
- Define one global element in the XML type and all other complex types as anonymous complex types within that element. Define one global element in the schema and define all other complex types as anonymous complex types within the element. Do not define any of the following:

- global attribute
- global attributeGroup
- global simple type

- Be sure that the name of an element in the anonymous complex type is unique within the entire schema definition.

Note: The name of an element of simple type need not be unique, unless the occurrence of the element is unbounded.

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

- Nested complex types
- Recurring references among complex types
- Multiple references from different complex type to a single complex type

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="http://www.w3.org/2001/XMLSchema">

>     <xsd:element name="Company">
>      <xsd:complexType>
>       <xsd:sequence>
>       <xsd:element name="Name" type="xsd:string"/>
>       <xsd:element name="CompanyAddress">
>        <xsd:complexType>
>         <xsd:sequence>
>          <xsd:element name="City" type="xsd:string"/>
>         </xsd:sequence>
>        </xsd:complexType>
>       </xsd:element>
>        <xsd:element name="Department">
>         <xsd:complexType>
>          <xsd:sequence>
>           <xsd:element name="Name" type="xsd:string"/>
>           <xsd:element name="DepartmentAddress">
>            <xsd:complexType>
>             <xsd:sequence>
>              <xsd:element name="City" type="xsd:string"/>
>             </xsd:sequence>
>            </xsd:complexType>
>           </xsd:element>
>          </xsd:sequence>
>         </xsd:complexType>
>        </xsd:element>
>       </xsd:sequence>
>      </xsd:complexType>
>     </xsd:element>
>     </xsd:schema>

#### Requirements for Simple Types

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

- Use xs:dateTime type in the XML type rather than xs:date, or xs:time, or any gXXX type, such as gMonth, etc. (If a physical date source uses gXXX type, you should rely on the use of an inverse function to handle the type for update. For gXXX types, you should rely on the use of a DSP update override function to handle the update.)

Note: The usage of inverse functions is described in "Best Practices and Advanced Topics", Data Services Developer's Guide.

- Base64Binary type should be used, rather than hexBinary type.
- Avoid using List or Union type.
- Avoid using xs:token type.
- Avoid defining default values in your XML type.
- The length constraining facet for 'String' should not be used.

#### Requirements for Target Namespace and Namespace Qualification

Requirements for using target namespaces and namespace qualification include:

- Your XML type must have a target namespace defined. Everything in the type should be under a single namespace.
- Set the elementFormDefault and attributeFormDefault to unqualified for the entire XML type. (As these are the default setting of a schema document, you can generally leave these two attributes of xs:schema unspecified.)

## References

Further information regarding XML schemas can be found at:

>     http://www.w3.org/TR/xmlschema-0

# Generated Artifacts Reference

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

- XML Schema Definition for ADO.NET Typed DataSet
- Web Services Description Language (WSDL) File for Microsoft ADO.NET Clients

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

>     msdata:IsDataSet="true"

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:

- A reference to the Microsoft-specific namespace definition, as follows:
  `xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"`
- Namespace declaration for the original target schema (the schema associated with the DSP data service)

Listing 6-1 shows an excerpt of a schema—`CustomerDS.xsd`—for a typed DataSet generated from a DSP Customer schema.

Listing 6-1 Example of a Typed DataSet (ADO.NET) Schema

>     <xs:schema xmlns:mstns="http://temp.openuri.org/schemas/Customer.xsd" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns="http://temp.openuri.org/schemas/Customer.xsd" targetNamespace="http://temp.openuri.org/schemas/Customer.xsd" id="CustomerDS" xmlns:xs="http://www.w3.org/2001/XMLSchema">

>       <xs:element msdata:IsDataSet="true" name="CustomerDS">

>         <xs:complexType>

>           <xs:choice maxOccurs="unbounded">

>             <xs:element ref="CUSTOMER"/>

>           </xs:choice>

>         </xs:complexType>

>     </xs:element>

>     <xs:element name="CUSTOMER">

>     . . .

>     </xs:element>

>     </xs:schema>

## 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="http://temp.openuri.org/schemas/Customer.xsd" 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:sequence>
>               <s:any namespace="http://temp.openuri.org/schemas/Customer.xsd"/>
>             </s:sequence>
>      </s:complexType>