Data Services Developer's Guide

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

Modeling Data Services

Using BEA Aqualogic Data Services Platform, you can create and maintain models of your enterprise data services. Models describe data, relationship between data objects, data semantics, and consistency constraints.

Models also express relationships between physical data services, logical data services, or a combination. In DSP all model relationships are binary; each binary relationship is expressed in a model diagram as one or more lines between two data services.

You can use DSP model diagrams to:

The following topics are covered in this chapter:

Note: For more information on data service modeling concepts see Modeling and a Service-Oriented Architecture in the AquaLogic Data Services Platform Concepts Guide.

Relationships Invalidated by Metadata Update Appear in Red

Figure 5-1 Model Diagram of Physical Data Services

Model Diagram of Physical Data Services

A model diagram is a graphical representation of a data model supported by DSP. In addition to showing collections of data services and relationships between data services, model diagrams also identify role direction and cardinality information at each end of the relationship. By default, types shown in model diagrams are XML schema types, but you can change this to display native data source types in the case of physical data services.


Model-Driven Data Services

In large enterprises modeling is — or at least should be — an early task in developing a data services layer. By starting with a graphical representation of physical data resources it is easier to view data resources globally, leveraging existing information in interesting and useful ways. It is also easy to see opportunities for creating additional business logic in the form of logical services.

Model diagrams are quite flexible; they can be based on existing data services (and corresponding underlying data sources), planned data services, or a combination. You can also create and modify data services and data service XML types directly in a modeler diagram.

In DSP model relationships are logical connections between two data services. The connections describe:

Relationships can have one or more navigation functions that allows data associated with one data service (such as Customer) to potentially become a complex parameter for a related data service (such as Orders).

Some relationships — such as between relational data services — are automatically inferred through introspection of primary and foreign keys. See Importing Relational Table and View Metadata for details.

Additional relationships can be created in several ways:

Logical and Physical Data Models

Models can represent any combination of logical and physical data services.

Physical Data Models

Physical data services represent data that physically resides in the enterprise (see Obtaining Enterprise Metadata). The source may be from a relational database, a Web service, an XML data stream or document, a flat file such as a spreadsheet, or a Java file contain custom functions.

Logical Data Models

Logical data models are developed in DSP and are based on physical other logical data.

In other words, each physical model entity represents a single data source. Logical data model entities represent composite views of physical and/or logical models.

Rules Governing Model Diagrams

Model diagrams follow a set of rules:

Note: Changes to a model diagram that affect data services such as when a new relationship is created are only made permanent in WebLogic Workshop after you do a File Arrow symbol Save All.


Building a Simple Model Diagram

You can create a data model by selecting a DSP-based project and then choosing:

File Arrow symbolNew Arrow symbolModel Diagram

The following example describes how to create a model around physical data.

Figure 5-2 Creating a Data Model Using the File Menu

Creating a Data Model Using the File Menu

This example assumes that you are using the DSP demonstration program RTLApp.

The data services used in the example in this chapter are PRODUCT, CUSTOMER_ORDER, and CUSTOMER_ORDER_LINE_ITEM. See Obtaining Enterprise Metadata for details related to importing metadata.

Here are the steps required to create and populate a simple model:

  1. First choose a name and physical location for your model. It can be created anywhere in your BEA WebLogic application. In the demonstration application provided with DSP, models are located in a MODELS folder.
  2. Right-click on your project and select NewArrow symbol Model Diagram.
  3. Pick a location for your model and name it myModel Diagram.
  4. Figure 5-3 Selecting a Data Service

    Selecting a Data Service

  5. Right-click in the work area of your new model and select Add Data Service.
  6. From the dialog box select the CUSTOMER_ORDER data service in Data Services/ApparelDB.
  7. Figure 5-4 Adding Data Services to a Data Model

    Adding Data Services to a Data Model

    Since the data services in this example are representations of relational sources, a considerable amount of metadata is available. For example, primary keys are identified from the data; these are shown in data service type as a key icon ( Adding Data Services to a Data Model).

  8. Right-click on the CUSTOMER_ORDER data service titlebar and choose the Add Related Services command.
  9. In this case you will see that two relationship already exists: CUSTOMER and CUSTOMER_ORDER_LINE_ITEM (Figure 5-5).

    Figure 5-5 Adding Related Services

    Adding Related Services

  10. Mouse over to the related data service that you want to add to your model diagram. For this example perform this operation twice, adding both related data services to your model.
  11. Once you have done this, you should automatically see the relationships between these three data services (Figure 5-6). (If not, try selecting the Show Relationship command for the Address data Service.)

    Figure 5-6 Automatically Inferred Relationships Between Physical Data Sources

    Automatically Inferred Relationships Between Physical Data Sources

    As described previously, relationship lines are graphical representations of relationship declarations and navigation functions.

    There is a role at each end of a relationship. Initially, role names simply reflect their respective data service. Table 5-7 details the model diagram's services, roles, and cardinality of the model diagram, shown in Figure 5-1.

    Table 5-7 Relationship Declarations in Sample Model's Data Services
    data service
    Role Name
    Role Number
    Opposite Role data service
    Current Role
    Minimum Occurrences
    Maximum Occurrences

Displaying Relationships Automatically

In the Application pane you can multi-select data services using either Shift-click (contiguous services) or Control-click (individual services). If you drag a set of data services into a model diagram, any existing relationships to other data services in the model will be created automatically.

The relationships shown in the example are based on automatically created navigation functions found in the respective physical data services (see Table 5-8).

Table 5-8 Navigation Functions in a Model's Data Services
data service
Navigation Function
Customer, Credit_ Card
getCustomer( )
getAddress( )

Generated Relationship Declarations in Source View

An example of a navigation function in the underlying source is:

(::pragma function <f:function xmlns:f="" kind="navigate" roleName="ADDRESS"/>::)

This specifies a relationship to the Address data service from the Customer data service.

Data services also contain declarations describing the nature of the relationship; this information is the source for the role names and cardinality values that appear in your model diagram.

For example, the data service Address contains the following relationship declarations:

<relationshipTarget roleName="CUSTOMER" roleNumber="1" XDS="ld:DataServices/CustomerDB/CUSTOMER.ds" opposite="ADDRESS"/>

For each data service, a relationship is created which identifies its role name, cardinality, opposite data service, and a unique (to the data service) role number.

In the above example, a navigation function is automatically created that retrieves customer information based on the customerID. The Customer data service getAddress( ) function is show in Listing 5-1.

Listing 5-1 Customer Data Service getAddress() Navigation Function
import schema namespace t2 = "ld:DataServices/CustomerDB/ADDRESS" at "ld:DataServices/CustomerDB/schemas/ADDRESS.xsd";

(::pragma function <f:function xmlns:f="" kind="navigate" roleName="ADDRESS"/>::)

declare function f1:getADDRESS($pk as element(t1:CUSTOMER)) as element(t2:ADDRESS)*
for $fk in f2:ADDRESS()
where $pk/CUSTOMER_ID eq $fk/CUSTOMER_ID
return $fk

In the case of the relationship between Customer and Address, the relationship is 0-to-n for the Address role (it can make and appearance any number of times or not at all) based on CustomerID being a foreign key in Address and a primary key in the Customer data service (and the underlying relational data sources respectively).

Since the relationships are bilateral, Customer's opposite is Address while Address's opposite is Customer. This is shown in the Properties Editor (Figure 5-9).

Figure 5-9 Property Editor for New Model Diagram

Property Editor for New Model Diagram

Modeling Logical Data

The major difference between a logical model and a physical model is that the logical model contains representations of at least one logical data service, in addition to physical data services. In practice there are no constraints between creating models that contain mixtures of logical or physical data services, including data services which are themselves composed of logical data services.

If your data model is composed of both physical and logical data services, you should keep in mind that a metadata update on any underlying physical data services will remove any relationships you have created involving those data services. For details see Updating Data Source Metadata.


Building Data Service Relationships in Models

In model diagrams, a relationship is created by the gesture of drawing a line from one data service to another (see Figure 5-1). In some cases (such as relational data services) relationships and the lines representing the relationship can be automatically inferred. In other cases, you need to create the relationship.

A relationship has several editable properties:

Navigation functions are visible as properties of each data service in the binary relationship. They can be fully inspected in Source View for each data service. Navigation functions also appear as mouse-over text over each endpoint of the relationship line.

Direction, Role, and Relationships

In a model diagram, each side of a relationship represents the role played by the adjacent data service. For example, in an ADDRESS: CUSTOMER relationship the end of the line near the customer is, by default, also called CUSTOMER. If you mouse over the role name, the opposite role name appears (Figure 5-10), as well as the name of the navigation function.

Figure 5-10 Model of Two Relational Data Services, ADDRESS and CUSTOMER

Model of Two Relational Data Services, ADDRESS and CUSTOMER

In the model diagram shown in Figure 5-10 the ADDRESS role is accessed by CUSTOMER through its primary key, ADDR_ID. In the CUSTOMER data service the ADDRESS relationship has an automatically created function called getADDRESS(). Its role is to return address-type information about the holders of specific credit cards.

Figure 5-11 getAddress(pk) Function in the CUSTOMER Data Service

getAddress(pk) Function in the CUSTOMER Data Service

In the function shown in Figure 5-11 the navigation function getADDRESS(pk) can take any CUSTOMER parameter input that includes a primary key CUSTOMER_ID and returns customer address information.

At the other end of the relationship in Figure 5-10 is the CUSTOMER role, which supplies customer information to the ADDRESS data service also based on a unique customer ID.

In Figure 5-10 notational arrows also identify cardinality notations. The ADDRESS role has a 0-to-1 cardinality with CUSTOMER, since your data source can have a customer without address information. The ADDRESS role has a 1-to-1 cardinality with CUSTOMER, since each ADDRESS must be identified with a single customer.

Cardinality notations can be modified in three places:

Role Names

You can change role names to better express the relationship between two data services. This is particularly useful when there are multiple relationships between two data services.

Take, for example: Customers and Orders. One relationship between these two data services would typically by 1: n, expressing two facts about the relationship:

By default, the role names would also be Customers and Orders. However you could change the role names to Supplies_Customer_Info and Orders_Array, respectively, to more precisely express the role of each side of the relationship.

A second relationship line could represent a different function, getMostRecentOrder( ). This relationship would be 1:1 and the roles could be expressed as CustInfo and getOrder.

Figure 5-12 Mousing Over a Role Displays Its Navigation Function Name

Mousing Over a Role Displays Its Navigation Function Name

If you mouse over the end of a relationship line you will either see the navigation functions defined for that particular role (Figure 5-12) or a message indicating that no navigation functions have been defined.


In a model diagram, drawing a line between two data services opens the Relationship Wizard.

Figure 5-13 First Dialog of Relationship Wizard

First Dialog of Relationship Wizard

The wizard allows you to specify:

Then, for each data service, you can additionally specify:

When you are done you will have created a fully functional navigation function.

For an example and additional details see Adding a Relationship to Your Data Service. With a few minor exceptions the Relationship wizard works the same when invoked in a model diagram as it does when you add a relationship to an existing data service.


Working with Model Diagrams

This section describes some of the common operations you will use when working with model diagrams.

Model Right-click Menu Options

You can edit your model using a combination of right-click menu options and the model Property Editor. Table 5-14 describes right-click options based on the functional area of the model diagram that is in scope.

Table 5-14 Data Model Options
Data Model
Add Data Service
Allows you to add one or several data services in your application to the current model diagram. The Add command brings up a file browser from which you can select a data service.
Alternatively, you can drag data services from the Application pane into the model either individually or in groups (press the Ctrl key to select non-contiguous data services from your application).
In the case of relational-based data services, dragging multiple data services into a model diagram at the same time will create relationships between the data services, if any exist. The relationships, of course, are based on primary/foreign key relationships that are available through imported metadata.
Note: If a data service is already represented in your diagram, dragging will have no effect.
New Data Service
Allows you to create a new data service. After selecting a name and physical location for the data service (.ds) file using a browser, the service is created and placed on the diagram.
Select All Nodes
Select all nodes in the model diagram.
Generate Report
Creates either a Summary or Detail report describing the data services in the model, their bilateral relationships, and a description of each data service. See Generating Reports on Your Models.
Find Data Service
Locates a data service within your model. See Locating Data Services in Large Model Diagrams for details.
Data Service
Opens the currently selected data service in Design View (see Creating a Data Service). Alternatively, double-click on the data service representation.
Add Related Data Service
The Add Related command is available when one or several data services are selected in the model. Add Related lists data services that contain navigation functions referencing your currently selected data source. Click on the service you want to add and then repeat the process to add other available related services, if any.
Remove Data Service
Removes the selected data service from the model diagram. Alternatively, use the Delete key.

Note: This operation does not affect the underlying data service.

Create Relationship to Another Data Service
Dialog allows you to select from a list of data services in the model diagram. As with drawing a line between two data services, this option brings up the Relationship wizard. (See Using the Relationship Wizard to Create Navigation Functions.
Show Relationship
Optionally displays/hides relationship lines associated with the currently selected data service. Click a relationship name in the sub-menu to select/deselect the display of its relationships.
Show/Hide Native XML Types
Optionally displays/hides native types for elements representing physical objects associated with simple data types. Example: VARCHAR(25).
Show/Hide Read Functions
Display/hides read functions associated with the data service.
Show Function Signatures
Displays/hides full read function signatures such as:

getAddress() as element(Address)

Relationship line
Remove Relationship
Removes the relationship from the diagram without affecting the underlying data service.
Delete Relationship
Removes relationship notations in each respective data services and removes the relationship line from the model diagram.
Show/Hide Role Name
Displays/hides the role name assigned to each side of the relationship.
Show/Hide Cardinality
Displays/hides the cardinality of each side of the relationship. Only relationships between relational sources typically display cardinality.
XML type
XML types can be edited in your model diagram. For important editing information see Editing an XML Type.

Creating Relationships in Model Diagrams

You can create additional relationship notations in model diagrams in several ways:

  1. By drawing a line between two data services in your model diagram.
  2. By right-clicking on a data service representation and selecting Add Related Data Service. Then select a data service from the sub-menu. The related data service will appear in the diagram along with a relationship line.
  3. By selected a data service already in the model. Right-click on your data service and select Create Relationship to Another Data Service. Then, from the dropdown list in the resulting dialog, choose the data service to which you want to create a relationship. This will create a relationship line between the two data service representations.
  4. By editing in Source View.

In the cases of options 1and 2, above, the Relationship wizard will appear. The wizard is fully described in Adding a Relationship to Your Data Service. Note that in the model diagram you do not have the option of changing the names of each side of the relationships since this has already been defined by the line connecting the two data services.

Locating Data Services in Large Model Diagrams

You can locate data services in your model diagram using the Find Data Services option, available from the right-click menu in your model diagram. Alternatively, use Ctrl-F when your model diagram is in focus.

Figure 5-15 Find Data Service Dialog Box

Find Data Service Dialog Box

Options include the ability to:

Wildcard character (?) and string (*) search is available.

Nodes matching the search criteria are highlighted and the model diagram view changes to show the first matching node.

Searches made during the current session can be retrieved using the drop-down combination listbox and entry field.

Generating Reports on Your Models

You can generate summary and detailed reports on the current model using the right-click Generate Report menu option, available from the title bar of your model. There are two types of reports: Summary and Detailed.

Creating a Model Report

When you choose the Create a Model Report right-click option you are asked to select a name for the HTML document that is generated. By default, the name of the summary report is:


and the name of the detail report is:

Figure 5-16 Model Report Generator Dialog Box

Model Report Generator Dialog Box

You can save the report to any location in your application (Figure 5-16) including to a new folder.

Model Report Format

The model report is in HTML format. When you initially run your report it opens in a WebLogic Workshop pane in HTML. A source tab is also available (Figure 5-17).

Figure 5-17 Sample Summary Model Report

Sample Summary Model Report

Note: Print your report from any browser or application that supports HTML printing.

Zoom Mode

For larger models you can use a display-only zoom option, available in the lower right-hand corner of your model diagram (Figure 5-19). When in zoom mode an "lock" icon appears, indicating that Zoom mode is active and the model is read only.

Editing XML Types in Model Diagrams

You can edit any data service XML type represented in your model diagram. For XML type options see Editing an XML Type.

Model Diagram Properties

Properties both reflect and define relationships created in the model diagram. Table 5-18 describes data model properties based on scope: data service, relationship, navigation functions, and XML type.

Table 5-18 Notable Data Modeling Properties
Data Service
Properties described in Managing Your Data Service.
data service1(Role 1) - data service2 (Role 2
Read only
Shows names of the related data services and their respective roles.
Role (1)
Provides information on Role 1.
Editable text
target data service
Read only
Name of data service1.
Drop down, editable
Minimum occurrences can be blank, 0, 1, or n.
Drop down, editable
Maximum occurrences can be blank, 0, 1, or n.
Role (2)
See above.
Same settings as Role (1).
Navigation function
Read only
Return Cardinality
Read only, 1 or *
Returns single type or an array
return type


How Changes to Data Services and Data Sources Can Impact Models

A model diagram is dependent on its components including physical data, logical data, and relationships, all of which are subject to change outside the model itself.

Changes in a qualified name or deletion of a data service or changes in the underlying data can all cause a data model to become an incorrect representation of data services and their relationships.

A model diagram is revalidated when:

You can also use the Property Editor to correct a qualified name reference or to delete a stale reference. See Model Diagram Properties for details.

How Metadata Update Can Affect Models

Updating metadata will remove any manually created relationships between affected data services. In your model diagram this change is represented by the relationship line, appearing in red. In such cases, you will need to recreate the relationship with the newly updated data services.

Figure 5-19 Relationships Invalidated by Metadata Update Appear in Red

Relationships Invalidated by Metadata Update Appear in Red

  Back to Top       Previous  Next