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 (http://msdn.microsoft.com). See that site for information about developing ADO.NET-enabled applications. |
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:
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 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.
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. |
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.
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.
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.
Customer.ds |
||
Customer.xsd |
||
CustomerDataSet.xsd |
||
Customer.jcx |
||
Customer.jws |
||
Customer_schema |
||
CustomerNET.wsdl |
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.
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.
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. |
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:
Note: | Due to a Microsoft limitation, the functions and procedures that you add to your Data Service control must belong to the same namespace. |
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. |
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:
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: |
Note: | http://download.oracle.com/docs/cd/E13222_01/wls/docs81/webservices.html |
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:
In a moment, the WSDL is generated; you will see it displayed as a node under the JWS file.
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.
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. |
There are several approaches to adapting XML types for use with an ADO.NET DataSet:
Note: | Any ADO.NET-compatible data service XML types can be consumed by non-ADO.NET clients. |
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 the Best Practices and Advanced Topics chapter of the Building Queries and Data Views.) |
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 supporting a complex type in an ADO.NET DataSet include:
Note: | The name of an element of simple type need not be unique, unless the occurrence of the element is unbounded. |
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="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 supporting simple types in an ADO.NET DataSet include:
Note: | The usage of inverse functions is described in the Best Practices and Advanced Topics chapter of the Building Queries and Data Views. |
Requirements for using target namespaces and namespace qualification include:
Further information regarding XML schemas can be found at:
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.
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:
Listing 9-1 shows an excerpt of a schema—CustomerDS.xsd
—for a typed DataSet generated from a AquaLogic Data Services Platform Customer 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>
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>