Data Services Developer's Guide
|
 |
 |
|
 |
 |
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:
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 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.
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:
Models can represent any combination of logical and physical data services.
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 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.
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
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:
Figure 5-3 Selecting a Data Service
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 (
).
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
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
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
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
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.
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.
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:
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
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
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.
This section describes some of the common operations you will use when working with model diagrams.
You can edit your model using a combination of right-mouse click menu options and the model Property Editor. Table 5-14 describes right-mouse click options based on the functional area of the model diagram that is in scope.
|
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. |
||
|
Allows you to create a new data service. After selecting a name and physical location for the data service ( |
||
|
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. |
||
|
Locates a data service within your model. See Locating Data Services in Large Model Diagrams for details. |
||
|
Opens the currently selected data service in Design View (see Creating a Data Service). Alternatively, double-click on the data service representation. |
||
|
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. |
||
|
Removes the selected data service from the model diagram. Alternatively, use the Delete key. Note: This operation does not affect the underlying 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. |
||
|
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. |
||
|
Optionally displays/hides native types for elements representing physical objects associated with simple data types. Example: |
||
|
Display/hides read functions associated with the data service. |
||
|
Removes the relationship from the diagram without affecting the underlying data service. |
||
|
Removes relationship notations in each respective data services and removes the relationship line from the model diagram. |
||
|
Displays/hides the role name assigned to each side of the relationship. |
||
|
Displays/hides the cardinality of each side of the relationship. Only relationships between relational sources typically display cardinality. |
||
|
XML types can be edited in your model diagram. For detailed editing information see Editing an XML Type. |
You can create additional relationship notations in model diagrams in several ways:
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.
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:
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.
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.
When you choose the Create a Model Report right-mouse 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.
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.
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.
You can edit any data service XML type represented in your model diagram. For XML type options see Editing an XML Type.
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
|
Properties described in Managing Your Data Service. |
|||
|
Shows names of the related data services and their respective roles. |
|||
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.
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
|
|
|
