Skip navigation.
Downloads | Product Documentation | Support

Data Services Developer's Guide

# Modeling Data Services

Using BEA Aqualogic Data Services Platform (DSP), 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:

- Obtain a high-level, visual view of data resources
- View the relationships between physical and logical data resources
- Facilitate the creation or modification of relationships between resources
- Quickly access or create a data service
- Modify a XML type of a data service

The following topics are covered in this chapter:

- Model-Driven Data Services
- Building a Simple Model Diagram
- Building Data Service Relationships in Models
- Working with Model Diagrams
- How Changes to Data Services and Data Sources Can Impact Models

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

Figure 5-1 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:

- The direction of the binary relationship (one- or two-way)
- The cardinality of the relationship (1-to-1, 1-to-many, 0-to-many, or many-to-many)
- A role name for each side of the relationship

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:

- Automatically, by dragging two or more relational-based data services into a model diagram simultaneously. In such cases primary/foreign key relationships are automatically identified.
- Graphically, through gestures you make in your model diagram.
- Programmatically, through Source View of a data service.

## 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:

- Each entity in the model has a title which is the data service local name (the fully-qualified name is visible as a mouse-over).
- Data services in models need not be associated with an XML type. However, if they are, the type is always displayed. For physical data services you have the option of displaying native schema types such as Integer(10).
- Associated read functions can be displayed, with or without signatures.
- Model diagrams do not "own" data services, but simply reference them. Multiple models can, without limit, contain representations of the same data service or relationships between data services.
- Models are not nested. That is, one model diagram cannot reference another.
- Multiple models can be defined and located anywhere in your project.
- Changes made to a model diagram can be reversed using the Edit —>Undo command. However it is important to keep in mind that changes to any underlying files such as schemas (XML types) or data services made through the model will not be undone. Instead, edit the data service directly or close and reopen your application before saving your changes.

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 —> Save All.

# Building a Simple Model Diagram

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

>     File —>New —>Model Diagram

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

Figure 5-2 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 New—> Model Diagram.
3. Pick a location for your model and name it myModel Diagram.

Figure 5-3 Selecting a Data Service

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

Figure 5-4 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 ( ).

6. Right-click on the CUSTOMER_ORDER data service titlebar and choose the Add Related Services command.

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

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

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

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
--- | --- | --- | --- | --- | --- | ---
Address | Customer | 1 | customer.xds | Address | 1 | 1
| CreditCard | 2 | credit_card.xds | Address | 0 | n
Credit_Card | Address | 1 | address.xds | Credit_card | 1 | 1
Customer | Address | 2 | address.xds | Customer | 0 | n

## 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 | Returns | Navigation Function
--- | --- | ---
Address | Customer, Credit_ Card | getCustomer( )
Customer | Address | getAddress( )

## Generated Relationship Declarations in Source View

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

>     (::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com" 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="urn:annotations.ld.bea.com" 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

## 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:

- Cardinality. Is the relationship zero-to-one (0:1 or 1:0) as in customer and promotion, one-to-one (1:1) as in customerID and custID, one-to-many (1:n) as in customers and orders, or many-to-many (n:n) as in customer orders and ordered items?
- Direction. Arrows indicate possible navigation paths. Is there an originating entity associated with a subordinate entity (such as orders and order items) or is the relationship bidirectional (such as customers and orders)?
- Roles. A name matching the name of the adjacent data services navigation function (see below). Does the assigned relationship name capture the purpose of the navigation function it represents?

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

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

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:

- Through your model diagram's Property Editor (see Model Diagram Properties).
- Through each data service Design View, using the Property Editor.
- Through Source View in each data service (not recommended).

### 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:

- There is no limit to the number of orders a customer may have made.
- An order must be associated with one and only one customer.

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

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.

### Relationships

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

Figure 5-13 First Dialog of Relationship Wizard

The wizard allows you to specify:

- Direction
- Role name
- Cardinality

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

- Join conditions
- Parameters

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

Scope | Command | Meaning
--- | --- | ---
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 | Open | 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 | Various | 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

Options include the ability to:

- Match case
- Restrict search to whole words only
- Restrict the search to regular expressions

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.

- Summary Report. Provides general information related the model including:

- Location of each data service in the model
- Type: logical or physical
- Allows updates: true/false
- Owner (if any)
- Comment (if any)
- Date created
- Date last modified

- Detail Report. A detailed model report contains all summary information listed above and, for each relationship between data services, the following additional information:

- Return type fully qualified name (known as the qname)
- Details on each read function including return type, description, and comments
- Details on the data service relationships including role name, target data service, minimum and maximum occurrences, opposite role name, navigation functions including return type, description, comment and user-defined properties
- Dependencies — a list of all dependent data services

### 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:

>     <model_name>_md_summary.html

and the name of the detail report is:

>     <model_name>_md_detail.html

Figure 5-16 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

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 Model Properties

Scope | Property | Settings | Comments
--- | --- | --- | ---
Data Service |  |  | Properties described in Managing Your Data Service.
Relationship | 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.
| role-name | Editable text |
| target data service | Read only | Name of data service1.
| min-occurs | Drop down, editable | Minimum occurrences can be blank, 0, 1, or n.
| max-occurs | Drop down, editable | Maximum occurrences can be blank, 0, 1, or n.
| Role (2) | See above. | Same settings as Role (1).
Navigation function | Name | Read only |
| Return Cardinality | Read only, 1 or * | Returns single type or an array
return type |  |  | See Editing XML Types and Return Types.

# 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:

- it is opened or regains focus
- when the application is saved
- when metadata is updated

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