Data Services Developer's Guide
|
 |
 |
|
 |
 |
A data service gives you access to a structured view of a unit of information in the enterprise such as a customer, sales order, product, or service.
Collectively, a set of data services comprise the data integration layer in an IT environment. For additional information on data services see Unifying Information with Data Services in the Liquid Data Concepts Guide.
Design View presents the data service as a "integrated chip" or schematic representation (Figure 4-1) of all the query functions, underlying data sources, navigational relationships, and transformation logic needed to support returning results in a particular arrangement, the return type. For details see Liquid Data Projects and Components.
A data service exists in a Liquid Data project as a single XQuery file containing query functions and metadata support. For details see Using Source View and the Liquid Data XQuery Developer's Guide.
For information on setting security and caching policies for functions and elements see Securing Liquid Data Resources" in the Administration Guide.
The following major topics are included in this chapter:
In modern enterprises there are increasingly two "data worlds": the traditional relational world of tables, columns, views, and stored procedures and the world of web services and other forms of data that is accessed through the desktop or through various Web interfaces.
Increasingly, the cost of accessing and updating data across systems with fundamentally different architectures and purposes can rival the cost of setting up the services themselves.
A data service is similar to a conventional web service in the following respects:
Of course a conventional web service does not have a core XML data type that allows for easy manipulation of the shape of the return data. Another minor difference is that data services can access private functions contained in XQuery library files (.xfl files).
In concrete terms, a data service is a file that contains XML Query (XQuery) instructions for retrieving, aggregating, and transforming data.
There are two types of data services: physical and logical. Physical data services comprise both relational and service data. Logical data services are consumers of physical or other logical data services. The data access layer of the enterprise includes both logical and physical data services.
An important benefit of this approach is that in the case of a virtual data access layer such as Liquid Data provides there is no transfer or storage of data — other than for application-controlled caching. Instead data services simply expose interface calls to read functions that dynamically retrieve data from data sources. The retrieved data is then arranged based on the data service's XML type. Update logic is associated with each data service. In the case of relational data the update logic is automatic; otherwise custom update functions can be developed (see Enabling SDO Data Source Updates in the Client Application Developer's Guide.
Data services should be designed so as to present client applications with a sensible, uniform data access layer for obtaining and updating data.
The data service interface consists of several types of public functions.
Note: The single submit() function can be found in Source View. It is not represented in the Design View of the data service.
Design View provides a means of visualizing the entire data service (see Figure 4-1). Each data service appears in WebLogic Workshop optionally bounded by panes that describe the application components, properties of selected Design View properties, and so forth. For details on Liquid Data project components see Liquid Data Projects and Components.
At the heart of each data service is its XML type. The XML type describes the shape of the document that will be returned when read functions are called either from this or a related navigation function. (For additional information see XML Types and Return Types.)
Figure 4-1 Components of a Data Service
Table 4-2 details the functional components of the data service shown in Figure 4-1.
|
Query functions are typically developed through the XQuery Editor. In Figure 4-1 the getCustomer() function accepts a custID and returns data in the shape of the customer XML type. (See Modifying a Return Type). |
||
|
The data services that are used as immediate building blocks for the current data service are shown. Click on its chevron symbol Note: Underlying data services are only displayed to one level. Use the Metadata Browser to identify all underlying data services and dependencies (see Viewing Metadata in the Liquid Data Administration Guide). |
||
|
Relationships that are both inferred (relational) or created are shown. Navigation functions return data in the shape of their native type. Clicking on the chevron symbol If you click on the function name your view will switch to the XQuery Editor. Relationships can be created through the Liquid Data modeler (see Modeling Data Services) or directly in your data service using the relationship wizard (see Using the Relationship Wizard to Create Navigation Functions). |
||
|
The XML type is represented by an editable XML schema. The return type of read functions shown in the XQuery Editor (see Using Query Editor View) should match the data service XML type. |
Note: Multiple data services can depend on a single XML type. In such situations it is advantageous to design such data services as a group, so that they always should return the same XML type.
A key product of Liquid Data projects are data service query functions and return types, sometimes called target schemas. XML schemas are used to represent in hierarchical form physical and logical data and the shape of documents returned from Liquid Data queries.
Return types can be thought of as the backbone of both data services and data models. Programmatically, return types are the "r" in for-let-where-return (FLWR) queries.
Return types have the following main purposes:
For more information on specifying the XML type in a data service see Associating an XML Type.
The Liquid Data modeler, data services, XQuery Editor, and Metadata Browser use XML type representations as follows:
For the versions of the XQuery and XML specifications implemented in Liquid Data see the Liquid Data XQuery Developer's Guide.
Return types describes the structure or shape of data that a query produces when it is run. A return type can be thought of as an object of XML type.
Note: In order to maintain the integrity of Liquid Data queries that will be used by your application, it is important that the query return type match the XML type in the containing data service. Thus if you make changes in the return type, you should use the XQuery Editor's "Save and associate schema" command to make the data service's XML type consistent with query-level changes. Alternatively, create a new data service based on your return type. For details see Creating a New Data Service and an XQuery Function.
You can create a data service in several ways:
Figure 4-4 Adding a Function to a New Data Service
Data services always reside in the current Liquid Data project. Once created, you can use the Data Service menu (or right-click) to develop your data service. Table 4-5 lists available right-mouse click options and their usage.
Table 4-5 Data Service Menu Options
Subsequent sections describe each of these commands in detail.
When adding a query function to your data service, you can accept the default function name or edit it directly. Then, when you click on the name of your new function, you will be placed in the XQuery Editor. See Using Query Editor View.
Note: It is important that function names in any given data service be unique even when their arity (number of parameters) does not match. This is because JDBC is not able to differentiate between functions of the same name.
Relationships allow you to call out to another data service using an instance of your data service as a parameter. Data is returned in the shape of the related service. In this way you can populate your data services with a set of functions.
Two data services can be related by one or more relationships.
For example, CUSTOMER and ORDER might be related by a CUSTOMER-ORDER relationship that has three navigation functions in all:
cst:getAllOrders(CUSTOMER)—> ORDER*
cst:getOpenOrders(CUSTOMER)—> ORDER*
ord:getCustomer(ORDER)—> CUSTOMER
The first two functions are different ways of navigating the CUSTOMER-ORDER relationship from a customer to all or some of their orders. The third function is a way to navigate from an ORDER to the associated CUSTOMER.
In the most common case, a relationship will result in the availability of two navigation functions, one for moving through the relationship in one direction and one for moving in the other direction.
In the less common case of a unidirectional relationship, there will be only one navigation function.
In a data service the functional difference between a read function and a navigation function is the shape of the returned data. Here is a simple example:
In a read function if you have an OpenOrders data service with an XML type of:
<openOrders>
<custID>
<first_name>
<last_name>
<orderID>
..
</openOrders>
and pass it a customer ID such as 101 and an order ID such as LRP-111. The query result appears as:
<customerInfo>
<custID>101</custID>
<first_name>Jane</first_name>
<last_name>Smith</last_name>
<orderID>Smith</orderID>
..
</customerInfo>
However, if your data service has a navigation function associated with a table called TrackOrders, the query parameter can remain the same but data will be returned in the shape of the TrackOrders type, which looks like this:
<TrackOrders>
<custID>
<first_name>
<last_name>
<orderID>
<ship_date>
<weight>
<delivery_date>
...
</TrackOrders>
In a data service adding a relationship is a three-part process:
You can develop fully-functional binary navigation functions using the Relationship wizard.
The value of navigation functions is that client applications can call the function using complex parameters without having to know the internal structure of function, join conditions, and so forth. From the perspective of the data service creator, the internals of the function can be changed without affecting applications dependent on the ability to invoke the data service function.
When you choose to create a relationship through Design View or within a model diagram, the Relationship wizard is invoked. With the wizard you can set the following navigation function notations:
You can also identify parameters and specify where clauses.
The first dialog of the Relationship wizard allows you to set role names, direction, and cardinality. Table 4-8 provides details on the callouts shown in Figure 4-7.
Figure 4-7 Relationship Wizard Specifying Direction, Cardinality, and Role Name
Table 4-8 Primary Relationship Settings
The second Relationship wizard dialog page allows you to set the navigation function name and other characteristics.
Figure 4-9 Relationship Wizard Dialog Specifying Function Name, Parameters, and Where Clauses
Table 4-10 provides details on callouts shown in Figure 4-9.
Table 4-10 Primary Relationship Settings
This section contains a small example showing how you can use the Relationship wizard to create fully-formed navigation functions. The goal is to create a navigation function that returns the first available address on file for a particular customer by supplying a customer ID.
The following steps use the RTLApp provided with Liquid Data.
Figure 4-11 Selecting a Target Data Service for the ApplOrder Navigation Function
The relationship remains bi-directional, meaning that you can get customer profile information by supplying an address object and you get can address information using a customer profile object. However, the cardinality relationship notation of Customer Profile
Figure 4-12 Setting Direction and Cardinality for the Relationship
Figure 4-13 Defining the First Navigation Function
The apparel orders data service more typically contains multiple read functions. If you select getApparelOrdersByCustID(), then you will be able to map an element (cust_id) from the opposite data service.
Notice in Figure 4-14 that the where clause you defined for the first navigation function is pre-determined and shown in read-only format.
Figure 4-14 Selecting a Parameter
Figure 4-15 Resulting getCustomerProfile() Navigation Function
When you execute a navigation function in Test View, you can provide input in the form of a complex parameter such as would result from, for example, getting back a customer record. Alternatively, you could use the Test View template option to supply the appropriate parameter. See Using an Input Parameter's Template to Guide Input.
In data service Source View the navigation function is defined through a pragma and a function body. (For details on Liquid Data Source View files see the Liquid Data XQuery Developer's Guide).
For example, a navigation function named Payment() has a read function getPaymentList().
The navigation function appears as:
declare function ns1:getCustomer($arg as element(ns0:APPL_ORDER)) as element(ns15:PROFILE)* {
for $b in ns16:getCustomerByCustID($arg/CustomerID)
return $b
};
A key element in understanding this function is in the namespace ns15 which imports the schema that models the XML type, PAYMENTList.xsd. The namespace is defined as:
import schema namespace ns15="urn:retailerType" at
"ld:DataServices/RTLServices/schemas/Profile.xsd";
Note: If you modify a role name in the pragma of your data service, and that relationship exists in any model diagram, then you will need to similarly modify the role name in any model diagrams in which the relationship appears. Otherwise the relationship will become invalid.
Read functions associated with data services return information in a particular shape, the XML type.
You can add or replace an XML type that has been associated with an data service using a browser. Your type must be located in the your application file structure.
If the schema you select has more than one global element, a dialog allows you to choose the global element you want to use.
Figure 4-16 Select Global Element Dialog Box
You can also edit any XML type. data service. Several XML type right-click menu options are available (Table 4-17).
Table 4-17 Right-click XML Type Editing Options
Another option, Enable Optimistic Locking, becomes available for elements in relational-based XML types under some conditions. See Enable/Disable Optimistic Locking.
Table 4-18 identifies how various right-click options apply to different XML type elements.
Table 4-18 XML Type Editing Options / Element Matrix
In some cases complex type components that appear in schemas will not appear in your XML type.
Warning: XML types are based on schemas which may be used by other data services. Similarly, all the functions in your data service should be written to return the XML type of your data service. For this reason, XML types should be modified carefully, with adequate backup in case you need to revert to a previous version.
In addition to the right-click menu described in Table 4-18, you can use the Go to source command to edit your schema file using WebLogic Workshop's assigned text editor.
You can choose to create an XML type for a new data service. Since your data service already has a name, you need only supply:
By default, the name of your data service is the same as the schema file name, the schema (XML type), and the target namespace all have the same name.
Figure 4-19 Create New Schema File Dialog
Once created, you can then use the data services built-in schema editor to create your schema. Alternatively, you can create a schema in a program such as XMLSpy.
There are several important pre-deployment tasks before you can make your data service available to client applications. This includes setting properties for your data service and it's functions.
Figure 4-20 Data Service Properties
You can use the Properties Editor (View
See Notable Data Service Properties.
Each data service contains a set of properties that control its update characteristics.
Note: For complete information on decomposition functions, override classes, optimistic locking settings, and other SDO-related information see Enabling SDO Data Source Updates in the Application Developer's Guide.
You can use the Allow Update option in the Property Editor to control whether calling applications can exercise update logic associated with your data service. This is especially important in regard to relational-based data services, since update logic is automatically available unless disabled.
Set the option to True to allow update; False to prevent updates.
In order to update non-relational sources that are associated with your data service you need to create an update override class. In addition, you may want to overwrite built-in update logic for relational sources to apply custom logic to the update process.
Before you can set the override class, you need to develop it. The steps involved are:
<javaUpdateExit className="nameOfYourJavaClass"/>
For information on developing an override class see Enabling SDO Data Source Updates in the Client Application Developer's Guide.
Note: Each data service can have only one update override class. However, multiple data services can share the same update override class.
The SDO update mechanism for relational data uses an optimistic locking policy to avoid change conflicts. With optimistic locking, the data source is not locked after the SDO client acquires the data. Later, when an updated is needed, the data in the source is compared to a copy of the data at a time when it was acquired. If there are discrepancies, the update is not committed.
Optimistic locking update policy is set for each data service. The following table lists the three optimistic locking update policy options.
For relational-based data service the Enable/Disable Optimistic Locking option becomes available for elements in its XML type when the optimistic locking property is set to Selected.
Figure 4-21 Data Service Allowing Updates and Optimistic Locking on Selected Fields
When active, the Selected Fields option allows you to validate optimistic locking logic prior to an update. Any number of fields can be selected through the right-click menu associated with the XML type. (If a complex element is selected, all its children are selected even though they are not so marked.)
When the Selected Fields option is picked, a right-mouse click toggle option named Enable/Disable Optimistic Locking becomes available. Multiple elements can be selected.
Figure 4-22 Selecting a Field to Disable Optimistic Locking Policy
In Figure 4-22 two fields are selected, PRODUCT_ID and QUANTITY.
These choices are reflected in the Source View pragma.
<optimisticLockingFields>
<field name="PRODUCT_ID"/>
<field name="QUANTITY"/>
</optimisticLockingFields>
For complete details on handling change conflicts based on optimistic locking policies see Enabling SDO Data Source Updates in the Client Application Developer's Guide.
For each function in your data service, cache can be set to True or False. If False, results from executing your query function cannot not be cached. If True, results from earlier invocations of your function will be cached based on caching policies that are set through the Liquid Data Administration Guide.
There are several things to keep in mind when considering whether to enable caching for a particular function.
To inspect or set the caching policies for a particular read function in your data service click on the arrow to the left of the name of the function and then set its caching policy through the Properties Editor.
Figure 4-23 Click Arrow to the Left of a Function Name to Inspect or Set Its Caching Policy
You need to build your application in order for cache policy changes effective.
Note: Function cache policy (True of False) set in a data service cannot be overridden through the Liquid Data Administration Console.
The following table identifies notable properties associated with various parts of your data service.
Table 4-24 Notable Data Service Properties
|
|
|
inside the underlying data service representation to view its functions that are used by the current data service. If you click on the function name itself the data service will open. (Use the Back button to return to the original data service.)
