> Samples Tutorial > Creating a Physical Data Service

Samples Tutorial

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Creating a Physical Data Service

A data service is simply a file containing XQuery functions and supporting structured information. The most basic data service is a physical data service, which models a single physical data source residing in a relational database, Web service, flat file, XML file, or Java function.

Data Services Platform approaches the problem of creating integration architectures by building data services around multiple physical data services. Therefore, in this lesson, you will create data services based on relational data included in the sample PointBase database provided with ALDSP:

 

Objectives

After completing this lesson, you will be able to:

 

Overview

A data service is a collection of one or several related query functions. The service typically models a unit of enterprise information, such as customer or product data.

The shape of a data service is defined by an XML type that classifies each 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. ALDSP uses the XML type to model and normalize disparate data into a unified view.

The data service interface consists of public functions that enable client-based consuming applications to retrieve data from the modeled data source.

 

2.1 Creating an ALDSP Application

Because a data service is part of a specific ALDSP project, and a project is part of a single WebLogic Workshop application, you will first need to create the application, and then a project, before creating a physical data service. (Alternatively, an existing application could be used; in that case you would simply create a ALDSP project within the application.)

An application, which is deployed as a single unit to an instance of WebLogic Server, is a J2EE enterprise application that ultimately produces a J2EE Enterprise Application Archive (EAR) file. This, in turn, provides you with a multi-user application that is ready for Internet deployment. Except in specific cases, such as accessing remote EJBs or Web services, an application is self-contained. The application's components may reference each other, but may not generally reference components in other applications. An application's components include:

An application should represent a related collection of business solutions. For example, if you are deploying two Web sites — one an e-commerce site and the other a human resources portal for employees — you would probably create separate WebLogic applications for each.

An application is also the top-level unit of work that you manipulate within the WebLogic Workshop environment. Only one application can be active at a time.

Objectives

In this exercise, you will:

Instructions

  1. Choose File Arrow symbol New Arrow symbol Application
  2. In the New Application dialog box, select Data Services Application.
  3. Enter Evaluation in the Name field.
Note: The sample code used to work on this tutorial uses Evaluation as the application name. Ensure that you name the ALDSP application as Evaluation so that the sample works successfully with your application.
  1. Click Create.
    2. Figure 2-1 Creating a ALDSP Application


    Creating a ALDSP Application

The components of the application are represented in a hierarchical tree structure in the Application pane. When you first create a Data Services application, the following default components are automatically generated:

Data Service project. Takes the name of your application (in this case, Evaluation). Within the project folder, there is initially a single component, the xquery-types.xsd file. This file is an XML Schema Definition (XSD) that describes the contents, semantics, and structure of the project.

Modules. Initially an empty folder.

Libraries. Contains the ld-server-app.jar file. This file contains various folders and files, as displayed in Figure 2-2.

Note: Initially, the Libraries folder is empty. The ld-server-app.jar file is imported only after you build the Evaluation project.

Security Roles. Initially an empty folder.

Figure 2-2 displays the default folders created for the Evaluation application.

Figure 2-2 Initial Application Structure

Initial Application Structure

 

2.2 Creating a Data Services Project

A project groups related files—data services, models, and metadata—within an application. Each application can support multiple projects. As you develop the application, you may want to create new projects for the following reasons:

To separate unrelated functionality. Each project should contain closely-related components. For example, if you want to create one or more data services that expose order status to your customers, and also one or more Web services that expose inventory status to your suppliers, you would probably organize these two sets of unrelated Web services into two projects.

To control build units. Each project produces a particular type of file when the project is built. For example, a Java project produces a JAR file. If you want to reuse the Java classes, you would segregate the Java classes into a separate project, and then reference the resulting JAR file from other projects in your application.

Although a default Data Services project is created when you create a new Data Service application, for this tutorial you will create a new project.

Objectives

In this exercise, you will:

Instructions

  1. Choose File Arrow symbol New Arrow symbol Project
  2. In the New Project dialog box, select Data Service Project.
  3. Enter DataServices in the Project name field.
  4. Click Create.
    5. Figure 2-3 Creating a New Data Service Project


    Creating a New Data Service Project

The components of your new Data Service project are represented in a hierarchical tree structure in the Application pane. At present, there is only one component in the project, the xquery-types .xsd file. This file is an XML schema definition that describes the contents, semantics, and structure of the project.

 

2.3 Creating Project Sub-Folders

Folders let you logically group different data services, and their associated files, within a single project. For example, if you had three data sources — one relational database containing tables for customer-oriented information and two Web services providing credit rating and information — you would probably want to create two folders, one for the database and one for the Web services.

Objectives

In this exercise, you will:

Instructions

  1. Right-click the DataServices project folder.
  2. Choose New Arrow symbol Folder.
  3. Enter CustomerDB in the Name field.
  4. Click OK.
  5. Repeat steps 1 through 4 to create additional data service folders for:

After adding these four folders, your DataServices project folder should look similar to Figure 2-4.

Figure 2-4 Project Sub-Folders

Project Sub-Folders

 

2.4 Importing Relational Source Metadata

When you installed DSP, several sample data sources were also installed. One such sample data source is the Avitek RTL PointBase database. It contains a number of relational database schemas that provide the metadata needed to build your physical data services, including:

A physical data service, which models physical data existing somewhere in your enterprise, is automatically generated when you import relational source metadata. Each generated physical data service represents a single data source that can be integrated with other physical or logical data services.

Objectives

In this exercise, you will:

Instructions

Note: WebLogic Server must be running. If it is not already running, start the server (see 1.3 Starting WebLogic Server) before you begin this exercise.
  1. Right-click the CustomerDB folder.
  2. Choose Import Source Metadata from the pop-up menu.
  3. Select Relational from the Data Source Type drop-down list and click Next.
    4. Figure 2-5 Select Data Source


    Select Data Source

  4. Specify the data source, by completing the following steps:
    1. Select cgDataSource from the Data Source drop-down list.
    2. Click Select All and then click Next.
      3. Figure 2-6 Select Data Source


      Select Data Source

      WebLogic Server fetches the specified data, and then displays the Select Database Objects to Import dialog box. The source metadata for each selected object will be used to generate a physical data service.

  5. Expand the RTLCUSTOMER and RTLBILLING folders, located in the left pane.
  6. Select all tables from both schemas and click Add. The selected objects display in the right pane.
    7. Figure 2-7 Selected Database Objects to Import


    Selected Database Objects to Import

  7. Click Next. A Summary dialog box opens, displaying the following information:
  1. Click Finish.
  2. Repeat steps 1 through 8 to import source metadata into the ApparelDB, ElectronicsDB, and ServiceDB folders, substituting the following information for steps 1 and 5:
    3. Table 2-9 Data Service Objects and Data Source
    Data Service Objects
    Data Source
    ApparelDB
    RTLAPPLOMS
    ElectronicsDB
    RTLELECOMS
    ServiceDB
    RTLSERVICE

The Application pane should appear similar to Figure 2-10. If you expand a data service's schema folder, you will see XSD files for each data service generated from the underlying data source.

Figure 2-10 New Data Services

New Data Services

 

2.5 Building a Project

Building a project simply means that the project's source code is compiled into machine-readable instructions. Each project produces a particular type of file when the project is built. For example, a Java project produces a JAR file.

Objectives

In this exercise, you will:

Instructions

  1. Right-click the DataServices project folder.
  2. Choose Build DataServices. It may take a few moments for the project to be built. When complete, you will see a message in the Build window, similar to that displayed in Figure 2-11. (If the Build window is not open, choose View Arrow symbol Windows Arrow symbol Build or press Alt+5.)
    3. Figure 2-11 Build Project Information


    Build Project Information

  3. Scroll through the Build window. As part of the Build process, ALDSP generates a number of files, including the following:
  1. (Optional) Expand the Libraries folder. You should see the DataServices.jar file.

 

2.6 Viewing Physical Data Service Information

A physical data service is automatically generated when you import source metadata and build the associated project. Each generated physical data service represents a single data source that can be integrated with other physical or logical data services.

When ALDSP generates a physical data service, it also generates XML data types, an XML Schema Definition (.xsd file), default query and navigation functions, and pragma information.

Objectives

In this exercise, you will:

Viewing XML type

An XML type, which derives from the data service's XML Schema Definition (XSD), is a structured XML document that classifies each element within the data service as a particular form of information, according to its allowable contents and units of data. For example, the XML type for the CUSTOMER data service is CUSTOMER, whose elements include:

Multiple data services can use a single XML type. ALDSP uses the XML type as the default superset of data elements that will be returned by a set of queries. This superset XML type, known as the Return type, models and normalizes data retrieved from the underlying data source, thereby transforming disparate data into a unified view.

Instructions

  1. In the Application pane, expand the CustomerDB folder.
  2. Double-click the CUSTOMER.ds file. The data service opens in Design View.
    3. Note: The data service automatically opens in the View workspace last used; if Design View is not currently open, click the Design View tab.
  3. In the middle of the data service representation you should see the CUSTOMER XML (also known as schemas) type for the data service, plus the XML classification for each element in the data service. Items marked with a question mark (?) are optional elements, which indicates: 1) if there is no data in the underlying data source, that element will not display in the data set returned by the data service and 2) a query function can succeed without providing any value for that particular element.
    4. Figure 2-13 Design View of XML Type


    Design View of XML Type

Viewing Native Data Type

A Native Data Type classifies each data element according to the definitions specified in the underlying data source. For relational data sources, ALDSP generates Native Data Type definitions based on the underlying database's table structure and column data definitions.

Instructions

  1. Right-click the CUSTOMER Data Service header on the Design View tab. (You can also right-click any empty space within the data service diagram.)
  2. Select Display Native Type. This will display the original data type for each element in the underlying data source.
  3. In the middle of the data service representation, you should see Native Types for each data element in the data service.
    4. Figure 2-14 Design View of Native Type


    Design View of Native Type

Viewing XML Schema Definition

An XML Schema Definition file (.xsd) corresponds exactly to the XML type of a data service. It defines the structure and content of an XML document, such as the XML type document. In other words, it defines the vocabulary, rules, and conventions for representing information in a system.

An .xsd file is organized as a flat catalog of complex elements, any attributes, and any child elements. For physical data services, ALDSP automatically generates a .xsd file from underlying data when the underlying data source's metadata is imported. Generated .xsd files are placed in the appropriate data service's schema directory.

Note: For logical data services, you must create a schema. You can use XQuery Editor View, discussed in Creating a Logical Data Service, to create such schemas (XSD files).

Instructions

  1. Right-click the CUSTOMER element, located in the XML type pane. A pop-up menu opens.
  2. Choose Go to Source to view the underlying schema information.
    3. Figure 2-15 XML Schema Definition


    XML Schema Definition

  3. After reviewing the XSD, click the Close box (X) in the upper-right corner of the source pane to return to Design View of your data service.
Note: Clicking the large red X will close WebLogic Workshop.

Viewing Generated Functions

The data service interface consists of public functions of the data service, which can be of several types:

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

Instructions

  1. In Design View, notice the public functions displayed in the left pane of the diagram. These functions, which were generated for the data service, include the following:
  1. (Optional) Right-click the CUSTOMER Data Service header and choose Display XML type from the pop-up menu. (You can also right-click any empty space within the data service diagram.)

Viewing Data Service Metadata

Metadata is simply information about the structure of data; it provides facts about the data service's data, format, meaning, and lineage. For example, a list of tables and columns within a database is metadata. ALDSP uses metadata to describe a data service: what information is provided by the data service and the information's lineage (that is, the source for the information.)

In addition to documenting data services for potential consumers, metadata helps you determine what data services are affected when inevitable changes occur in the underlying data source layer. Of course in the case of physical data services, the metadata primarily describes metadata extracted from the physical data source.

Metadata information is contained in the data service's META-INF folder. Normally you should not need to refer to the contents of this folder.

Instructions

  1. Select the Source View tab. The metadata information used by the Customer data service appears. (Also available in Source View are data service namespace, schema namespace, and XQuery functions.)
  2. Click the + icon to display all metadata information.
  3. Notice the following:
Note: Before you test any function or data service, you should ideally clean and redeploy the application, so that the data is updated on the WebLogic server also.
  1. To clean the application, right-click Evaluation and select Clean Application.
  2. To redeploy the application, right-click Evaluation and select Deployment Arrow symbolRedeploy.

 

2.7 Testing Physical Data Service Functions

Testing a data service's functionality within Test View lets you determine whether the data service is able to return the expected data results.

Objectives

In this exercise, you will:

Instructions

  1. Select the Test View tab.
  2. Select CUSTOMER() from the function drop-down list.
  3. Click Execute. You should see data returned from the RTLCUSTOMER database, formatted according to the CUSTOMER data service's Return type, which is defined by each element's XML type.
Note: At times the WebLogic server may not get updated automatically. In that case, you may get some validation errors when you execute the function. To fix this, try cleaning and redeploying the application.
  1. Expand the nodes and notice the following:

    2. Each element defined by the XML type returns specific data retrieved from the RTLCUSTOMER database. For example, the <FIRST_NAME> element returns "Jack" as an xs:string, while the <CUSTOMER_SINCE> element returns "2001-10-01" as an xs:date.

    Figure 2-18 Physical Data Service Test Results


    Physical Data Service Test Results

  2. To view the results in the Output window, you need to enable auditing in the ALDSP console. To enable auditing:
    1. Open the ALDSP console, typically located at http://localhost:7001/ldconsole.
    2. Log on using the following credentials:
      • User = weblogic
      • Password = weblogic
    3. Expand ldplatform in the left-hand menu and click Evaluation.
    4. Click the Audit tab.
    5. Select the following options in the Global Settings section: Enable Auditing, Audit Queries, Audit Administrative Actions, Audit Updates, Send Audit Events Asynchronously, and Enable Logging of Audit Events (Figure 2-19).
    6. Select the At Default Level option from the Configure all Properties list in Audit Properties.
    7. Click Apply.
      8. Figure 2-19 Audit Tab in the ALDSP Console


      Audit Tab in the ALDSP Console

    8. In the left-hand menu, expand Evaluation, DataServices, and then CustomerDB as shown in Figure 2-20.
    9. Click Customer and select the Admin tab.
    10. Click the Audit tab.
    11. Select the check box in the Enable Audit column for the CUSTOMER function.
      12. Figure 2-20 Enabling Function-Level Auditing
      Audit Tab in the ALDSP Console
    12. Click Apply. This enables auditing for the CUSTOMER () function.
Notes:
  1. In WebLogic Workshop Arrow symbolTest View, click Execute again.
  2. Open the Output window (View Arrow symbol Windows Arrow symbol Output).
  3. Confirm that the output is similar to that displayed in Figure 2-21.
Note: You can use the Output window to verify that each element in the data service is pulling data from the correct data source. In this example, the return results are pulled from the RTLCUSTOMER database, CUSTOMER table 1, and a specific column (c1, c2, c3, and so on) for each element.
Figure 2-21 Test Results Output

Test Results Output

 

Lesson Summary

In this lesson, you learned how to:


  Back to Top       Previous  Next