As noted in Tutorial 2, there are two types of data services: physical and logical. Physical data services model a single physical data source residing in a relational database, Web service, flat file, XML file, or Java function.
To enable the integration of data from multiple sources through Data Services Platform (ALDSP), you define a logical data service. In this lesson you will create a logical data service that integrates data from the CUSTOMER data service.
Objectives
After completing this lesson, you will be able to:
Create a simple logical data service, define its shape, and specify its query conditions
Test the logical data service's read, write, and limit functions
Overview
A logical data service integrates data from two or more physical or logical data services. Its shape is defined by an XML type schema that classifies a data element as a particular form of information, according to its allowable contents and units of data. For example, an xs:string type can be a sequence of alphabetic, numeric, and/or special characters, while an xs:date type can only be numeric characters presented in a YYYY-MM-DD format.
The data service interface consists of public functions that enable client-based consuming applications to retrieve data from the modeled data source. A data service's functions can be of several types:
One or more read functions, which typically return data in the form of the XML type.
One or more navigate functions, which return data from related data services. Within a logical data service, you must define relationships through modeling. Although similar to relationships in the RDBMS context, a logical data service lets you establish relationships between data from any source. This gives you the ability to, for example, relate an ADDRESS relational table with a -STATE look-up Web service.
One submit() function, which allow users to persist changes to the back-end storage
In addition to public functions, a data service can include private functions and side effect functions. Private functions are only used within the data service. They generally contain common processing logic that can be used by more than one data service function. Side effect functions can be invoked from the client side. For example, a side effect function can contain code to update a non-RDBMS data source, such as xml, flat files, and Web services, and clients can invoke this function to perform updates. (For more information, see the Data Service Developer's Guide.)
Every function within a logical data service also includes source-to-target mappings that define what results will be returned by that function. There are four types of mappings:
A simple mapping means that you are mapping simple source node elements to simple elements in the Return type one at a time. You can create a simple mapping by dragging and dropping any element from the source node to its corresponding target element in the Return type. Optional Return type elements do not need to be mapped; otherwise elements in the Return type need to be mapped to run your query.
An induced mapping means that a complex element is mapped to a complex element in the Return type. In this gesture, the top level complex element in the Return type is ignored (source node name need not match). The editor then automatically maps any child elements (complex or simple) that are an exact match for source node elements.
An overwrite mapping replaces a Result type element and all its children (if any) with the source node elements. As an example of the general steps needed to create an overwrite mapping, you would press <Ctrl>, then drag and drop the source node's complex element onto the corresponding element in the Result type. The entire source node's complex element is brought to the Result type, where it completely replaces the target element with the source element.
An append mapping adds a simple or complex element (and any children or attributes) as a child of the specified element in the Return type. To create an append mapping, select the source element, then press <Ctrl>+<Shift> while dragging and dropping the source node's element onto the element in the Return type that you want to be the parent of the new element(s).
Alternatively, if you simply want to add a child element to a Return type, you can drag a source element to a complex element in your Return type. The element will be added as a child of the complex element and mapped accordingly.
In addition to the mappings, each function can also include parameters and variations on the basic XQuery FLWOR (for-let-where-order by-return) statements that further define the data retrieval results.
When you click on the name of a data service in the Application pane (Figure 2-10), your data service will open in Design View (Figure 3-1). In the Customer data service, what you see in Design View is a logical data service that:
Uses the getAllCustomers(), getCustomer(), getPaymentList(), and getLatePaymentList() functions to retrieve data.
Uses the customer.xsd schema definition to define its XML type, and thus its Return type.
Integrates data from the ApparelDB and CustomerDB physical data services, plus a CreditRating Web service.
Figure 3-1 Design View of a Logical Data Service
If you open XQuery Editor View for a particular function, you would see the function's source-to-target mappings.
If you open Source View, you would see each function's parameters and FLWOR statements.
3.1 Creating a Simple Logical Data Service
A logical data service integrates and transforms data from multiple physical and logical data services.
Objectives
In this exercise, you will:
Create a new folder for the logical data service.
Create an empty data service that can be built into a logical data service.
Import a pre-defined XML schema definition that you will associate as the logical data service's XML type.
Define functions and their mappings, parameters, and FLWOR statements.
Instructions
Create a new folder within the DataServices project and name it CustomerManagement.
Create a new data service within the CustomerManagement folder by completing the following steps:
Right-click the CustomerManagement folder.
Choose New Data Service. The New File dialog box opens.
Confirm that Data Service Data Service are selected.
Enter CustomerProfile in the Name field.
Click Create.
Figure 3-2 New Data Service
A new data service is generated, but without any associated data services or XML type.
3.2 Defining the Logical Data Service Shape
A data service transforms received data into the shape defined by its Return type. Pragmatically, the Return type is the "R" in a FLWOR (for-let-where-order by-return) query. A Return type, which describes the structure or shape of data returned by the data service's queries, serves two main purposes:
Provides a superset of data elements that can be returned by an XQuery.
Defines the unified structure, and order of the data returned by an XQuery.
The Return type is generated from the data service's XML type. An XML type classifies a data element as a particular form of information, according to its allowable contents and units of data. For example, an xs:string type can be a sequence of alphabetic, numeric, and/or special characters, while an xs:date type can only be numeric characters presented in a YYYY-MM-DD format.
Objectives
In this exercise, you will:
Import a schema file, which you will associate with the data service's XML type.
Review the results.
Instructions
Note:
Although you can use ALDSP to graphically build a schema file, in this exercise you will import a pre-defined schema file to save time. For more information on using WebLogic Workshop to create the XML types, see the Data Service Developer's Guide.
Create a new folder in the CustomerManagement folder and name it schemas.
Import a schema file into the schema folder by completing the following steps:
Right-click the schema folder, located in the CustomerManagement folder.
Choose Import.
Navigate to:
<beahome>\weblogic81\samples\liquiddata\EvalGuide
Select the CustomerProfile.xsd file.
Click Import.
Figure 3-3 Import XML Schema Definition File
Right-click the CustomerProfile Data Service header on the Design View tab.
Choose Associate XML Type.
Select the CustomerProfile.xsd file, located in:
CustomerManagement\schemas
Click Select.
Figure 3-4 Associating XML type with XSD
You should see that the CustomerProfile data service is now shaped by the CustomerProfile.xsd file.
You should also see that several of the elements are identified with a question (?) mark. This indicates that these elements are optional. Because the schema file identifies these elements as optional, ALDSP will not require the mapping of these elements to the Return type; however, if mapped to the Return type and there is no corresponding data in the underlying data source, then the result set will not include the empty elements.
Figure 3-5 Logical Data Service XML type
3.3 Adding a Function to a Logical Data Service
A data service consumer—a client application or another data service—uses the data service's function calls to retrieve information. A logical data service includes the same types of functions that are found in a physical data service:
One or more read functions that form the data service's external interface, which is exposed to consuming applications requesting data. These read functions typically return data in the form of the data service's XML type.
One or more navigate functions that return data from other data services. Within a logical data service, you must define relationships through modeling. Although similar to relationships in the RDBMS context, a logical data service lets you establish relationships between data from any source. This gives you the ability, for example, to relate an ADDRESS relational table with a STATE lookup Web service.
One submit() function, which allows users to persist changes to the back-end storage.
Objectives
In this exercise, you will:
Add a new read function, getAllCustomers(), to the logical data service.
View the results in XQuery Editor View.
Instructions
Right-click the CustomerProfile Data Service header.
Choose Add Function. A new function displays in the left pane of the data service model.
Enter getAllCustomers as the function name.
Figure 3-6 Design View of New Function
3.4 Mapping Source and Target Elements
In the previous exercise, you associated a logical data service with an XML Schema Definition (.xsd file), which generated a Return type that includes all data elements defined within the schema. However, there are no conditions associated with the Return type; conditions specify which source data will be returned.
You can define conditions by mapping source and target (Return) elements.
Objectives
Add a physical data service function as a data source for the logical data service.
Create a simple map between the source node and the Result type.
Instructions
Click the getAllCustomers() function to open XQuery Editor View. You should see a Return type populated with the CustomerProfile schema definition. The Return type determines what data can be made available to consuming applications, as well as the shape (string, data, integer, and so on) that the data will take. The Return type was automatically populated when you associated the logical data service with the CustomerProfile.xsd.
Figure 3-7 XQuery Editor View of Function Return Type
In the Data Services Palette, expand CustomerDB\CUSTOMER.ds. If the Data Services Palette is not open, choose View Windows Data Services Palette.
Figure 3-8 Data Services Palette
Drag and drop CUSTOMER() into XQuery Editor View. This method call represents a root or global element within the CUSTOMER physical data service (see 3.2 Defining the Logical Data Service Shape). A for node for that element is automatically generated and assigned a variable, such as For: $CUSTOMER. Within the XQuery Editor View, this for node is a graphical representation of a for clause, which is an integral part of an XQuery FLWOR expression (for-let-where-order by-return).
Figure 3-9 Source Node and Return Type
Create a simple map by dragging and dropping individual elements from the $CUSTOMER source node onto the corresponding elements in the Return type. The logical data service CustomerProfile should now be similar to what is shown in Figure 3-10.
Note:
There are alternatives to mapping elements instead of using the slow simple mapping technique. Faster mapping techniques are described in exercises that follow.
Figure 3-10 Simple Mapping Between Source Node and Return Type
3.5 Viewing XQuery Source Code
When you use XQuery Editor View to construct an XQuery, source code in XQuery syntax is automatically generated. You can view this generated source code in Source View and, if needed, modify the code. Any changes made in Source View will be reflected in XQuery Editor View.
Objectives
In this exercise, you will:
View generated XQuery source code in Source View.
Review the for and return clauses of the getAllCustomers() query function.
Instructions
Select the Source View tab. A portion of the generated XQuery source code is displayed in Figure 3-11.
Notice the for clause, which references the CUSTOMER() function.
Notice the return clause, which reflects the simple mapping between the $CUSTOMER source node and the Return type. All optional elements are identified with a question mark in the field description, as shown (emphasis added):
<TelephoneNumber?> {fn:data(CUSTOMER/TELEPHONE_NUMBER)}</Telephone number
Also, notice that the <orders> elements are empty because order information has not yet been mapped to the Return type. This means that a consuming application, using this query, will only see customer information, not order information.
Figure 3-11 Source View of XQuery Code for CUSTOMER() Node
3.6 Testing a Logical Data Service Function
You can use Test View to validate the functionality of a logical data service.
Objectives
In this exercise, you will:
Build the DataServices project.
Test the function's retrieve and limit result capabilities.
Instructions
Build the DataServices project by right-clicking the DataServices folder and choosing Build DataServices from the pop-up menu.
After the build completes successfully, select the Test View tab.
Select getAllCustomers() from the function drop-down list.
Test the ability to specify the number of tuples returned by completing the following steps:
Uncheck the Validate Result option. This feature is not mandatory to complete this exercise.
Enter CustomerProfile/customer in the Parameter field (or select from the drop-down list). This parameter specifies the XPath expression for the element whose return results you want to limit to a set number of occurrences (such as customer).
Enter 5 in the Number field. This will limit the results to the first five customers retrieved.
Click Execute.
Figure 3-12 Test Truncate Capabilities
View the results, which appear in the Result pane.
Expand the top-level node. There should be only five Customer Profiles listed.
Expand the first <customer> node. You should see a Customer Profile for Jack Black, as displayed in Figure 3-13.
Figure 3-13 Customer Profile Test Results
Lesson Summary
In this lesson, you learned how to:
Create a simple logical data service.
Associate an XML schema definition with the data service.
Create a simple function.
Use XQuery editor view to map elements from the source node to the return type.
Use Source View to examine an XQuery function's source code.
Use Test View to test a logical data service query capabilities, limit the number of data set results returned as part of the query, and test data service editing capabilities.
Windows 
