Data Services Developer's Guide
|
 |
 |
|
 |
 |
BEA Aqualogic Data Services Platform (DSP) can be added to WebLogic Workshop in two ways:
The basic menus, common behavior, and look-and-feel associated with WebLogic Workshop apply to DSP.
Note: WebLogic Workshop online documentation is available at:
http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/index.html
This chapter discusses various WebLogic Workshop facilities that you can use in creating and managing your DSP-based projects. DSP extensions to WebLogic Workshop are also described from an interface perspective.
The following topics are covered:
As noted above, you can create a WebLogic Workshop application that automatically includes a Data Services Platform project. Or you can add DSP projects to any BEA WebLogic application.
Note: It often makes sense to consolidate DSP queries into a WebLogic Workshop application dedicated to DSP development. Other applications can then access these queries through the DSP Mediator API or a Data Services Platform control. For complete details related to how client applications can access Data Services Platform functions and procedures see the DSP Client Application Developer's Guide.
To ascertain that DSP is available to your application or to determine the version of DSP that you are running, start your BEA WebLogic Server and access its Administration Console.
As an example, the WebLogic Server Console for the sample domain provided with BEA WebLogic can be accessed from:
http://localhost:7001/console
Navigate to the Console
To create a DSP-based application select File
Figure 2-1 Creating a New Data Services Platform Application
You probably will want to change the name of the application from Untitled to something else. Your new application automatically contains an initial DSP-based project.
Figure 2-2 Application View of a New Data Services Platform Application
You can save your application at any time using the File
When you initially create a WebLogic Workshop application such as "myLD", a file called myLD.work is created in the root directory of your application. Invoking Workshop using this file also opens your application.
An application can contain any number of DSP or other types of WebLogic Workshop projects.
You can also add one or several DSP projects to any WebLogic Workshop application.
To do this select File
Figure 2-3 Application Tab of a New Data Services Platform Application
When a new Data Services Platform application or project is created, a DSP project folder is also created. This becomes the root directory of your project (see Figure 2-3). Two Java archive (.jar) files are added to the application's Libraries folder including ld-server-app.jar and the mediator.jar. The latter file manages creation of Service Data Objects (SDOs), described in detail in the Client Application Developer's Guide.
Table 2-4 lists major DSP file types and their purposes.
Table 2-4 Data Services Platform Components, Including File Types
|
Data services are contained in DS files and can be located anywhere in your application. Each data service file is an XQuery document. Note: Since a |
|
|
Model diagrams provide a graphical representation of the relationships between various data services, which themselves represent the physical and logical data services available to your DSP queries. Model diagrams have the extension |
|
|
Metadata information is contained in META-INF folders associated with JAR files. The non-editable contents of this Libraries folder contains information on data sources used by data services. |
|
|
Data services typically are associated with XML types whose physical representation is an XML schema file. Schema files can be located anywhere in your application. Schemas automatically created by the Metadata Import wizard are placed in a Schema files can be manually created or modified using any text editor. There is also a built-in schema editor in DSP Design View and in model diagrams containing the data service. The XML type associated with a data service is also the return type of each function in your data service.The return type precisely describes the shape of the document to be returned by your query. The return type can be modified through the XQuery Editor or directly in source. However, this generally should only be done in conjunction with the Save and Associate Schema command (see Creating a New Data Service and Data Service Function for details). |
|
|
XQuery function libraries typically contain utility XQuery functions that can be used by application data services and in building data transformations. A typical example would be a routine for converting currencies based on daily exchange rate. Such transformational functions could be used by any data service in your application. |
Other files which may appear in DSP projects include Java files containing custom update logic and SDO configuration files such as sdo.xsdconfig, which allows XMLBean technology to create SDOs rather than XMLBeans.
WebLogic Workshop is fully described in on-line and printed documentation. A good place to start is:
http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/index.html
Alternatively, WebLogic Workshop provides complete on-line help.
Figure 2-5 Some WebLogic Workshop Components in a DSP-Based Project 
The following table briefly describes:
Table 2-6 Summary of WebLogic Workshop Pane Used by DSP
Table 2-7 describes the several WebLogic Workshop menu commands you will use with DSP projects.
Table 2-7 Summary of WebLogic Workshop Menu Services Used by DSP
|
When working with DSP projects you will often use the following File menu options: |
You can use the Property Editor to view details related to any WebLogic Workshop artifact (see Figure 2-8). For example, in Design View (see Design View) if you click on the general data service, the Property Editor provides details on that service. If you click on a relationship representation in your data service, property details on that relationship appear. In many cases, property settings are editable or configurable.
Figure 2-8 Relationship Properties in a Data Service
WebLogic Workshop provides a comprehensive file search facility with its Find in Files option, available from the Edit menu (Edit
Figure 2-9 Workshop File Search Facility
You can use Find in Files to search for references to any DSP artifacts such as particular data sources, use of functions, and so forth.
A DSP project adds menu items and views to the basic WebLogic Workshop environment to support the following functionality:
Data services are central to creating data models and physical and logical data views that can be used in DSP queries. The first step in creating a data service is to import metadata from physical data sources so that corresponding physical data services can be created.
Figure 2-10 Selecting Metadata Import for a DSP Project
For details related to importing and updating metadata into your DSP project see Obtaining Enterprise Metadata.
Through the data model interface that you can:
Figure 2-11 Creating a Data Model Diagram from the File Menu
For details on developing and maintaining data models see Modeling Data Services.
Every data service provides a Design View, XQuery Editor View, Source View, Test View, and Query Plan View. Each data service is based around a single XQuery source file. And every data service has an associated XML type (XDS file).
Data services are composed of read and navigation functions and procedures. Read functions must return the XML type of the data service. Navigation functions, return the XML type of their native data service. Procedures, also known as side-effecting functions, need not return anything.
Figure 2-12 Sample Data Service
Design View is the central reference point of every data service. Through Design View that you can:
For details on developing and maintaining data services see Designing Data Services.
Through the XQuery Editor View you can develop query functions by projecting data service function elements, as well as transformations, to the function's return type.
Figure 2-13 Sample XQuery Editor Query with Its Return Type
The graphical editor directly supports common constructs of the 1.0 XQuery standard. Several resources are available to help in the development and maintenance of business logic. These are all available from the WebLogic Workshop View or View
For details on developing queries using XQuery Editor View see Working with the XQuery Editor.
An XQuery function palette (Figure 2-14) is available that supports standard XQuery and BEA-specific functions. This function palette is also available from the Workshop View
Figure 2-14 XQuery Function Palette
Like all Workshop panes, the XQuery Function Palette can be placed anywhere in the WebLogic Workshop window. Functions from this palette can be dragged into XQuery Editor View, as well as Source View.
DSP projects also have access to the XQuery Constructs palette (Figure 2-15). This palette supports creation of different types of XQuery statements in the XQuery Editor View or Source View. Many of the construct prototypes such as FLWGR, FGWOR, FWGR, and so forth are variations on the most common XQuery construct, FLWR (for-let-where-return).
Figure 2-15 XQuery Constructs Palette
For example, FLWGR adds the DSP extension Group By. The prototype is shown below in Source View.
for $var in ()
let $var2:=()
where (true)
group by () as $var3 with partitions $var as $var4
return
()
For details on Group By and other BEA XQuery extensions see the XQuery Developer's Guide.
The Data Services Palette (Figure 2-16) is only available to DSP projects. It provides the DSP XQuery Editor with access to data service and XFL (XQuery function library) routines.
Figure 2-16 Data Services Palette
For details on using the XQuery Editor see Working with the XQuery Editor.
A schema editor for modifying XML types in model diagrams and data services, as well as return types in the XQuery Editor, is available. See Working with Logical Data Service XML Types. Most editor options are available from the right-click menu.
Right-click menu commands for return types differ slightly from those in the XML type editor. The reason is that you can use the XQuery Editor to create if-then-else constructs, zones, and cloned elements as a means of more exactly specifying the form your query result document should take. (See Modifying a Return Type.)
Figure 2-17 Editing an XML Type Element
After you have developed a query you can run it using Test View. For details see Testing Query Functions and Viewing Query Plans.
If you are working in Source View you can easily add pre-built XQuery functions and constructs to your source, as well as make other editing changes to your data service. For additional details see Working with XQuery Source.
You can review the query plan developed by DSP for a particular function in order to verify the generated SQL or look for opportunities to improve performance. See Analyzing Queries Using Plan View.
You can create XQuery libraries containing functions that can be used by any data service in your application. XQuery function libraries can be created in two ways:
An XQuery function library (.xfl file) is ideal for creating transformation, security, and other types of functions that are not associated with an XML type.
An XQuery function library (XFL) holds any number of functions.
XFL Design View is similar to the data service Design View (shown in Sample Data Service). The primary differences are:
The tabular modes available in data services — Source View, XQuery Editor View, Test View, and Query Plan View — are available to XQuery function libraries as well.
XFL files play an important role in creating inverse functions. See Using Inverse Functions to Improve Performance During Updates in Best Practices and Advanced Topics.
It is not difficult to make a function in a data service available throughout your project as an XML function library.
Note: Namespace conflicts must to be resolved before you can make your function generally available.
The following function is available in the RTLApp's DataServices/RTLServices/Credit Card data service (namespace declarations from a separate section of the source file are also included):
declare namespace ns1="ld:DataServices/BillingDB/CREDIT_CARD";
import schema namespace ns0="urn:retailerType" at "ld:DataServices/RTLServices/schemas/CreditCard.xsd";
declare namespace tns="ld:DataServices/RTLServices/CreditCard";
(: ... :)
declare function tns:getCreditCard() as element(ns0:CREDIT_CARD)* {
for $CREDIT_CARD in ns1:CREDIT_CARD()
return <ns0:CREDIT_CARD>
<CreditCardID>{fn:data($CREDIT_CARD/CC_ID)}</CreditCardID>
<CustomerID>{fn:data($CREDIT_CARD/CUSTOMER_ID)}</CustomerID>
<CustomerName>{fn:data($CREDIT_CARD/CC_CUSTOMER_NAME)}</CustomerName>
<CreditCardType>{fn:data($CREDIT_CARD/CC_TYPE)}</CreditCardType>
<CreditCardBrand>{fn:data($CREDIT_CARD/CC_BRAND)}</CreditCardBrand>
<CreditCardNumber>{fn:data($CREDIT_CARD/CC_NUMBER)}</CreditCardNumber>
<LastDigits>{fn:data($CREDIT_CARD/LAST_DIGITS)}</LastDigits>
<ExpirationDate>{fn:data($CREDIT_CARD/EXP_DATE)}</ExpirationDate>
{fn-bea:rename($CREDIT_CARD/STATUS,<Status/>)}
{fn-bea:rename($CREDIT_CARD/ALIAS,<Alias/>)}
<AddressID>{fn:data($CREDIT_CARD/ADDR_ID)}</AddressID>
</ns0:CREDIT_CARD>
Here are the steps you would take to create this function in an XQuery library:
Source for the XQuery library file containing the CREDIT_CARD function appears below. To simplify, the object is returned as $x rather than as a set of individually-mapped elements.
(::pragma xfl <x:xfl xmlns:x="urn:annotations.ld.bea.com"></x:xfl> ::)
xquery version "1.0" encoding "WINDOWS-1252";
declare namespace tns="lib:DataServices/MyXQueryLibrary";
declare namespace ns1="ld:DataServices/BillingDB/CREDIT_CARD";
import schema namespace ns0="urn:retailerType" at "ld:DataServices/RTLServices/schemas/CreditCard.xsd";
(: function pragma removed for readability :)
declare function tns:getCreditCard() as element(ns1:CREDIT_CARD)* {
for $x in ns1:CREDIT_CARD()
return $x
};
It is often convenient to determine which Data Services Platform artifacts are in use by which other artifacts. For example, before making changes in an XML type it is important to determine what other data services might be impacted. Of course you can do this through the Metadata Browser, described in the "Viewing Metadata" chapter of the DSP Administration Guide. However, it is often more convenient to do this in the context of the WebLogic Workshop navigation pane or the DSP Design View.
For example, in the RTLApp, right-clicking on a data service shows a number of options including Find Usages (Figure 2-19).
Figure 2-19 Finding Usages of a Data Service in RTLApp
When you pick this option, usages of the artifact are displayed, as shown in Figure 2-20.
Figure 2-20 Usages of the Customer Data Service in the RTLAPP
You can find the usages of the following types of DSP artifacts:
When you save a DSP application its JAR libraries files are bound to that application. If you subsequently migrate to a newer version of DSP, you also need to migrate your application to the latest library files. For details see "Migrating Legacy DSP Applications" in the DSP Installation Guide.
DSP attempts to rebuild your application as necessary. However, there are times when you will need to initiate a build directly.
The following table describes relevant Build menu options and their uses.
You need to rebuild your project whenever you delete a file from a DSP-based project. Rebuilds can occur on a project or at the application level. Generally speaking, there is no need to rebuild your entire application unless you have made changes to multiple projects.
Rebuild your project (or application) in two steps:
Note: If you try to run a function in Test View and it fails unexpectedly, it is often curative to clean, then rebuild your application before attempting to run your query again.
If your application is already deployed, it will be automatically redeployed whenever you rebuild it. Under some conditions you may want to undeploy your application first. The following table describes relevant options available when you click on your application folder in the Application pane.
Table 2-21 Usages of Various Deployment Menu Options
|
Note: When you build your application it is automatically redeployed. |
|
|
First removes your application from the server, then redeploys it. |
|
For additional information on deploying WebLogic Workshop applications see:
After you have created and tested your application's query functions, you need to make them available to client applications. The SDO mediator API is the primary means of providing access to your updatable functions.
Note: For details on SDO programming and accessing data in Java clients through the mediator API see the Data Services Platform Client Application Developer's Guide.
One way to create the SDO mediator client Java archive (.jar) file is through the right-click menu option Build SDO Mediator Client. This is only available from the root folder of your application.
When successful, your SDO mediator client will be created in the root directory of your application. The file will be named as:
<name_of_your_application>-ld-client.jar
The SDO mediator JAR file will also be automatically added to your application's Libraries folder.
Note: Insure that all of your projects are up-to-date and built before creating your SDO mediator JAR file. See also Building, Deploying, and Updating Applications on page 2-22.
You can also create the SDO mediator client JAR file through the command line using ant scripts.
If you already have an EAR file you can use the script:
ant -f $WL_HOME/liquiddata/bin/ld_clientapi.xml
-Darchive=</your_path/name_of_your_application>.ear>
in which case the name of your JAR file will be taken from the EAR file:
<name_of_your_application>-ld-client.jar
It will be created in the same directory as the EAR file.
You can generate an SDO mediator client JAR file (without needing an EAR file) by simply specifying an application directory:
ant -f $WL_HOME/liquiddata/bin/ld_clientapi.xml
-Dapproot=</your_path/name_of_your_application>/root>
This approach will use the directory name of the application root to compute the JAR file name; in the above case the name would be root-ld-client.jar. If that's not what is wanted, you could specify:
-Dsdojarname=<MyApp-ld-client.jar>
to override this. Either way the JAR file will be generated in the application root directory.
For either case you could specify the additional ant parameter:
-Doutdir=</path/to/dir>
to generate the JAR file to a specific directory location.
-Dtmpdir=</path/to/tmp>
to specify an alternate directory for temporary files, including the generated .java code.
The default tmp file location is specified by the Java system property:
java.io.tmpdir
In any case, when building from the command line, the SDO mediator.jar file will not be added to your application's Libraries folder (shown in Figure 2-2).
There are times when you will want to move, rename, or delete artifacts in your Data Services Platform projects. A typical example: your application is first developed with test data, so as to not expose confidential information to unauthorized individuals. Then, once developed, your application is ready for deployment with the actual, secured data sources. You can use refactoring to greatly simplify the renaming, deleting, or relocating of DSP components.
Figure 2-22 Refactoring Options Available for the RTLApp's Address Data Service
Without refactoring, changes you make to artifact names can easily result in invalid references. For example, renaming a data service file automatically invalids any relationship functions in other data services that refer to that file. The alternative to refactoring is to manually find all usages of a given artifact and make manual edits to data service source; this can be quite tedious and error-prone, particular as projects grow.
When you use the Refactor option you initially see the effect your refactoring change will have on impacted application artifacts (Figure 2-23). A checkbox allows you to exempt any artifact from the refactoring operation.
Note: Care should be taken when deselecting elements recommended for refactoring. Without additional manual changes to the underlying source you likely will no longer be able to build or deploy your application.
Figure 2-23 Artifacts Impacted by a Refactoring
Table 2-24 describes artifacts subject to refactoring and their options.
Table 2-24 Data Service Artifacts Supporting Refactoring and Available Refactoring Options
|
Rename selected prefix or propagate the change through the project. |
|
|
Rename selected schema import prefix or propagate the renaming through the project. |
Move, rename, and add/remove parameter operations are typically accomplished without adverse consequence. Delete operations, however, can adversely affect your project. For this reason the usages of the artifact you have identified for deletion are shown (see Figure 2-25). From this information you can easily determine the trade-offs between the automation of the refactoring operation and its consequences, which may require additional manual actions on your part.
Figure 2-25 Implications of a Safe Delete Operation
Access to refactor options depends on the artifact:
Figure 2-26 Refactoring a Data Service Function
You can refactor a namespace or external schema prefix simply by changing its prefix name (binding) in the Property Editor (Figure 2-26).
Figure 2-27 Refactoring Namespace Declarations
When you change a prefix binding you are also given the option of making the change throughout your project (globally).
If you choose this option (see anywhere the uri (urn:retailerType) appears in your project, the prefix will become "retailer1".
Figure 2-28 Changing a Prefix Binding Throughout Your Project
If you choose Yes, a list of usages of the URI appears.
Figure 2-29 List of Prefix Bindings Potentially Affected by a Global Prefix Change
Warning: Although you can deselect any artifact that you do not want to be included in a refactor operation, doing so will invalidate that artifact and any files dependent on that artifact. For this reason selective deselection of artifacts scheduled for refactoring should generally not be employed.
Note: In the case of namespace prefixes, names should be changed (or not) based on readability or consistency issues. Neither a local or a global change will adversely affect your code.
It is useful to understand the various potential effects of a refactoring operation.
In this section each type of refactoring operation is described in terms of its potential impact on related artifacts.
|
|
|
