Skip navigation.
Downloads | Product Documentation | Support

Data Services Developer's Guide

# Designing Data Services

A data service gives you access to a structured view of a unit of information in the enterprise such as a customer, sales order, product, or service.

Collectively, a set of data services comprise the data integration layer in an IT environment. For additional information on data services see Unifying Information with Data Services in the BEA Aqualogic Data Services Platform Concepts Guide.

Design View presents the data service as a "integrated chip" or schematic representation (Figure 4-1) of all the query functions, underlying data sources, navigational relationships, and transformation logic needed to support returning results in a particular arrangement, the return type. For details see Data Services Platform Projects and Components.

A data service exists in a DSP-based project as a single XQuery file containing query functions and metadata support. For details see Working with XQuery Source and the Data Services Platform XQuery Developer's Guide.

For information on setting security and caching policies for functions and elements see Securing Data Services Platform Resources" in the Administration Guide.

The following major topics are included in this chapter:

- Data Services in the Enterprise
- Data Service Design View Components
- Creating a Data Service
- Managing Your Data Service

# Data Services in the Enterprise

In modern enterprises there are increasingly two "data worlds": the traditional relational world of tables, columns, views, and stored procedures and the world of Web services and other forms of data that is accessed through the desktop or through various Web interfaces.

Increasingly, the cost of accessing and updating data across systems with fundamentally different architectures and purposes can rival the cost of setting up the services themselves.

#### Comparing Data Services with Web Services

A data service is similar to a conventional Web service in the following respects:

- It consists of public functions.
- The functions that access services are modular, reusable, and extensible.
- Implementation details are hidden.

Of course a conventional Web service does not have a core XML data type that allows for easy manipulation of the shape of the return data. Another minor difference is that data services can access private functions contained in XQuery library files (`.xfl` files).

In concrete terms, a data service is a file that contains XML Query (XQuery) instructions for retrieving, aggregating, and transforming data.

## Physical and Logical Data Services

There are two types of data services: physical and logical. Physical data services comprise both relational and service data. Logical data services are consumers of physical or other logical data services. The data access layer of the enterprise includes both logical and physical data services.

An important benefit of this approach is that in the case of a virtual data access layer such as the Data Services Platform provides there is no transfer or storage of data — other than for application-controlled caching. Instead data services simply expose interface calls to read functions that dynamically retrieve data from data sources. The retrieved data is then arranged based on the data service's XML type. Update logic is associated with each data service. In the case of relational data the update logic is automatic; otherwise custom update functions can be developed (see Enabling SDO Data Source Updates in the Application Developer's Guide.

Note: Logical data services are built upon physical data services which in turn represent an underlying physical data source. Physical data service are created by importing metadata on a physical source and updated through synchronization. The schema file or XML type generated by this process should never be modified either in DSP or externally. Doing so risks invalidating your data service and dependent logical data services. (If you need to modify a data service based on a single source it is a simple matter to create a logical data service based on that one source.)

## Data Service Functions

Data services should be designed so as to present client applications with a sensible, uniform data access layer for obtaining and updating data.

The data service interface consists of several types of functions:

- Read functions. Return data in the form of the data service's XML type. Read functions can be developed either in the XQuery Editor or through Source View. Data services are ideal for encapsulating any number of specific functions with roles such as "Get all customers with pending orders", "Find customer number ___ ", and so forth.
- Procedures. Procedures are also known as side-effecting functions. They refer to external functions that typically return void. Procedures are identified during the metadata import process and are only associated with physical data services. Sources for procedures include Java routines, Web services, and relational stored procedures.
- Navigation functions. Return data in the form of a related data service's XML type using an instance of the current data service as a parameter. SeeUnderstanding Navigation Functions.
- Private functions. In addition to public functions, a data service or a XQuery function library (`.xfl` file) can contain private functions. Private functions can be accessed only by other functions within the data service or XFL. Such functions generally contain common processing logic, that is, operations for use in more than one function in the data service. (For functions designed to be shared across data services, see XQuery Function Libraries.)

In Source View you will notice that private functions are so identified in the pragma statement above the function.

- A submit function. Allows clients to persist changes (update) to underlying (physical) data.

Note: The single submit() function can be found in Source View. It is not represented in the Design View of the data service.

# Data Service Design View Components

Design View provides a means of visualizing the entire data service (see Figure 4-1). Each data service appears in WebLogic Workshop optionally bounded by panes that describe the application components, properties of selected Design View properties, and so forth. For details on DSP-based project components see Data Services Platform Projects and Components.

At the heart of each data service is its XML type. The XML type describes the shape of the document that will be returned when read functions are called either from this or a related navigation function. (For additional information see XML Types and Return Types.)

Design View displays:

- Read functions, also called query functions, that return data according to the XML type associated with the service. Navigation functions to related data services; these return data in the shape of their native XML type.
- Immediate underlying physical and logical data services and their read functions.

Figure 4-1 Major Visual Components of a Data Service

Table 4-2 details the functional components of the data service shown in Figure 4-1.

Table 4-2

Key | Component | Purpose
--- | --- | ---
1 | Query functions and procedures | Read function and DSP procedures are typically developed through the XQuery Editor. Read functions provide an API for the data service. In Figure 4-1 the getCustomer() function accepts a custID and returns data in the shape of the customer XML type. (See Modifying a Return Type). Procedures refer to functions which have side effects; often such functions return void.
2 | Base data services | The data services that are used as immediate building blocks for the current data service are shown. Click on its chevron symbol inside the underlying data service representation to view its functions that are used by the current data service. If you click on the function name itself the data service will open. (Use the Back button to return to the original data service.) Note: Underlying data services are only displayed to one level. Use the Metadata Browser to identify all underlying data services and dependencies (see Viewing Metadata in the Data Services Platform Administration Guide).
3 | Navigation functions | Relationships that are both inferred (relational) or created are shown. Navigation functions return data in the shape of their native type. Clicking on the chevron symbol inside your relationship representation, you will see the navigation functions that are defined for that relationship. If you click on the function name your view will switch to the XQuery Editor. Relationships can be created through the Data Services Platform modeler (see Modeling Data Services) or directly in your data service using the relationship wizard (see Using the Relationship Wizard to Create Navigation Functions).
4 | XML type | The XML type is represented by an editable XML schema. The return type of read functions shown in the XQuery Editor (see Working with the XQuery Editor) should match the data service XML type.
5 | Private functions | Private functions are only available to other functions in the data service. They appear in Design View between read functions and navigation functions.

Graphical Components of a Data Service

Note: Multiple data services can depend on a single XML type. In such situations it is advantageous to design such data services as a group, so that they always should return the same XML type.

## XML Types and Return Types

A key product of DSP-based projects are data service query functions and return types, sometimes called target schemas. XML schemas are used to represent in hierarchical form physical and logical data and the shape of documents returned from DSP queries.

Return types can be thought of as the backbone of both data services and data models. Programmatically, return types are the "r" in for-let-where-return (flwr) queries.

Figure 4-3 Sample Return Type from the RTLApp

Return types have the following main purposes:

- Provide a template for the mapping of data from a variety of data sources.
- Help determine the arrangement of the XML document generated by the XQuery.

For more information on specifying the XML type in a data service see Associating an XML Type.

### Where XML Types are Used

The Data Services Platform modeler, data services, XQuery Editor, and Metadata Browser use XML type representations as follows:

- Modeler. A DSP Model shows the relationships and cardinality between data services, as well as read query functions. For details see Modeling Data Services.
- Data Service. A data service generally contains an editable return type.
- Data Sources. Hierarchical-structured XML types represent both relational and non-relational data. For details see Obtaining Enterprise Metadata.
- XQuery Editor. The XQuery Editor uses physical and logical data source representations and transformational functions to develop queries that are mapped to a return type. For details see Working with the XQuery Editor.
- Metadata Browser. The Metadata Browser can display the return type associated with a data service. For details see Viewing Metadata in the Data Services Platform Administration Guide).

For the versions of the XQuery and XML specifications implemented in DSP see the DSP XQuery Developer's Guide.

Note: Data services supporting ADO.NET have additional, specific XML type requirements. For details see "Supporting ADO.NET Clients" in the Client Application Developer's Guide.

### Where Return Types are Used

Return types describes the structure or shape of data that a query produces when it is run. A return type can be thought of as an object of XML type.

Note: In order to maintain the integrity of DSP queries used by your application, it is important that the query return type match the XML type in the containing data service. Thus if you make changes in the return type, you should use the XQuery Editor's "Save and associate schema" command to make the data service's XML type consistent with query-level changes. Alternatively, create a new data service based on your return type. For details see Creating a New Data Service and Data Service Function.

# Creating a Data Service

You can create a data service in several ways:

- Through the DSP Metadata Import wizard, which automatically generates physical data services from available data sources. See Obtaining Enterprise Metadata.
- By selecting a DSP-based project and then choosing File —> New —> Data Service. Alternatively, right click on the project folder and choose New —> Data Service.
- By selecting Create Data Service from a data model and then opening the newly-created data service. See Modeling Data Services.

Figure 4-4 Adding a Function to a Data Service

Data services always reside in the current DSP-based project. Once created, you can use the Data Service menu (or right-click) to develop your data service. Table 4-5 lists available right-click options and their usage.

Table 4-5 Data Service Menu Options

Command | Usage
--- | ---
Add Function | Adds a function to your data service. After entering a name for the function, clicking on the name will open the XQuery Editor.
Add Function (empty) | Adds an empty function to your data service. An empty function will not initally contain a representation of the XML type even if a type is associated with your data service. In such cases, the schema "mark-up" can be added manually. This is particularly useful in cases where your XML type contains a large number of elements, many of which will not be used in the query functions planned for the data service.
Add Relationship | Creates a relationship to another data service. A file browser allows you to enter the name of the data service which you want to relate to your current data service. This, in turn, will bring up the Relationship wizard, where you can define the navigation functions that will relate the two services.
Add Private Function | Adds a private function to your data service. After entering a name for the function, clicking on the name will open the XQuery Editor.
Associate XML Type | Associates your data service with an XML type. You can choose the type (`.xsd` schema) from anywhere in your application. If your data service currently has an associated XML type, it will be replaced.
Create XML Type | Allows you to create an XML type using the built-in schema editor. Note: Once your data service is associated with a XML type, this option becomes unavailable.
Display XML Type / Display Native Type | For physical data services you can display either the element's XML type (example: xs:int) or its native type (example: CUSTOMERID INTEGER(10) ).

Subsequent sections describe each of these commands in detail.

## Adding a Function to Your Data Service

Read functions can be accessed by any calling application with the appropriate security credentials. When adding a read function to your data service, you can accept the default function name or edit it directly. Then, when you click on the name of your new function, you will be placed in the XQuery Editor. See Working with the XQuery Editor.

Note: It is important that function names in any given data service be unique even when their arity (number of parameters) does not match. This is because JDBC is not able to differentiate between functions of the same name.

## Adding a Procedure to Your Data Service

Data service procedures or side-effecting functions enable you to invoke external routines that do not necessarily return data. A common scenario would to use a procedure to invoke a Web service which in turn updates data. Another use of a procedure would be to invoke a relational stored procedure which in turn performs a database operation. The only thing returned in such a case might be a "success" message and that would only happen if the stored procedure was designed to report its status and the calling procedure was set up to handle such returned data.

Procedures are added to physical data services only, as part of the metadata import process. For details see Identifying DSP Procedures.

## Adding a Private Function to Your Data Service

A private function is similar to a read function, but it is only available to other functions in your data service. You can change a private function to a read function through the Property Editor or by editing the Source View pragma.

## Adding a Relationship to Your Data Service

Relationships allow you to call out to another data service using an instance of your data service as a parameter. Data is returned in the shape of the related service. In this way you can populate your data services with a set of functions.

### Understanding Navigation Functions

Two data services can be related by one or more relationships.

For example, CUSTOMER and ORDER might be related by a CUSTOMER-ORDER relationship that has three navigation functions in all:

>     	cst:getAllOrders(CUSTOMER) —> ORDER*

>     	cst:getOpenOrders(CUSTOMER) —> ORDER*

>     	ord:getCustomer(ORDER) —> CUSTOMER

The first two functions are different ways of navigating the CUSTOMER-ORDER relationship from a customer to all or some of their orders. The third function is a way to navigate from an ORDER to the associated CUSTOMER.

In the most common case, a relationship will result in the availability of two navigation functions, one for moving through the relationship in one direction and one for moving in the other direction.

In the less common case of a unidirectional relationship, there will be only one navigation function.

### Effect of Using a Navigation Function to Return Data

In a data service the functional difference between a read function and a navigation function is the shape of the returned data. Here is a simple example:

In a read function if you have an OpenOrders data service with an XML type of:

>     <openOrders>
>     			<custID>
>     			<first_name>
>     			<last_name>
>     			<orderID>
>     			..
>     </openOrders>

and pass it a customer ID such as 101 and an order ID such as LRP-111. The query result appears as:

>     <customerInfo>
>     			<custID>101</custID>
>     			<first_name>Jane</first_name>
>     			<last_name>Smith</last_name>
>     			<orderID>Smith</orderID>
>     			..
>     </customerInfo>

However, if your data service has a navigation function associated with a table called TrackOrders, the query parameter can remain the same but data will be returned in the shape of the TrackOrders type, which looks like this:

>     <TrackOrders>
>     			<custID>
>     			<first_name>
>     			<last_name>
>     			<orderID>
>     			<ship_date>
>     			<weight>
>     			<delivery_date>
>     			...
>     </TrackOrders>

### Creating a Relationship Between Data Services

In a data service adding a relationship is a three-part process:

1. Add and name the relationship.

Figure 4-6 Adding a Relationship to a Data Service Using Right-click Menu Option

2. Associate the relationship with an existing data service.
3. Use the Relationship wizard to define the relationship.

### Using the Relationship Wizard to Create Navigation Functions

You can develop fully-functional binary navigation functions using the Relationship wizard.

The value of navigation functions is that client applications can call the function using complex parameters without having to know the internal structure of function, join conditions, and so forth. From the perspective of the data service creator, the internals of the function can be changed without affecting applications dependent on the ability to invoke the data service function.

When you choose to create a relationship through Design View or within a model diagram, the Relationship wizard is invoked. With the wizard you can set the following navigation function notations:

- Role names
- Direction
- Cardinality

You can also identify parameters and specify where clauses.

#### Setting Relationship Notations: Role Names, Direction, Cardinality

The first dialog of the Relationship wizard allows you to set role names, direction, and cardinality. Table 4-8 provides details on the callouts shown in Figure 4-7.

Figure 4-7 Relationship Wizard Specifying Direction, Cardinality, and Role Name

Table 4-8 Primary Relationship Settings

Key | Component | Purpose
--- | --- | ---
1 | Direction | Query functions are typically developed using the XQuery Editor. A bidirectional relationship is the default condition. This means that each data service will have a navigation function that invokes the related data service. Direction notations have no run-time effect. Direction can also be specified through the Property Editor associated with each data service or through a model diagram.
2 | Role name | Each end of a relationship can have a target role name. By default, the role name is the same as its adjacent data service. For example, the default role name for the ADDRESS data service is ADDRESS. You can change the role name in the Relationship wizard. Role names can also be specified through the Property Editor associated with your data service or through a model diagram showing the relationship. Note: Role name notations have no run-time effect.
3 | Cardinality | Cardinality notations can be set for each side of the relationship. The default cardinality is 1-to-1 but this can be changed to any combination of <blank>, 0, 1, and n. Cardinality can also be specified through the Property Editor associated with your data service or through a model diagram showing the relationship. Note: Cardinality notations have no run-time effect

#### Setting Function Name, Identifying the Opposite Data Service, Mapping Parameters, and Building Where Clauses

The second Relationship wizard dialog page allows you to set the navigation function name and other characteristics.

Figure 4-9 Relationship Wizard Dialog Specifying Function Name, Parameters, and Where Clauses

Table 4-10 provides details on callouts shown in Figure 4-9.

Table 4-10 Primary Relationship Settings

Key | Component | Purpose
--- | --- | ---
1 | Navigation function name | By default, the navigation function name is the name of the target data service with "get" prepended, as in "getCustomer". If a function of that name exists, numbers will be appended to the function name as in getCustomer1. However, you can change the navigation function name to any valid function name. Note: When you invoke the Relationship wizard through a model diagram the opposite data service is determined by the gesture of drawing a line from one data service to another. In such cases the option of selecting a navigation function name is not present.
2 | Related data service function | By default, the root function in the target data service is selected. However, you can select any available read function in the target data service.
3 | Map input parameters | If the related function has input parameters, the name and type of the available parameters are displayed. You can then use a pulldown menu to select an element from the target data service to map as the input parameter.
4 | Build WHERE clause | Where clauses can be added to the function using pulldown menus that allow you to select join elements from each side of the relationship.
5 | Add or Remove | Allows you to add additional where clauses or delete a selected where clause.
6 | Next | When the relationship between data services is bidirectional clicking Next changes the focus to the second data service, where you can identify a navigation function name, parameters, and add where clauses for the second side of the relationship.

### Example of Creating a Navigation Function

This section contains a small example showing how you can use the Relationship wizard to create fully-formed navigation functions. The goal is to create a navigation function that returns the first available address on file for a particular customer by supplying a customer ID.

The following steps use the RTLApp provided with DSP.

1. Starting with the RTLServices/ApplOrder data service in Design View, select Add Relationship from the right-click menu.
2. Select a target data service. In this case RTLServices/CustomerProfile.

Figure 4-11 Selecting a Target Data Service for the ApplOrder Navigation Function

3. Next you can set direction and cardinality.

The relationship remains bidirectional, meaning that you can get customer profile information by supplying an address object and you get can address information using a customer profile object. However, the cardinality relationship notation of Customer Profile —> Address is 1-to-n, since a customer can have multiple orders.

Figure 4-12 Setting Direction and Cardinality for the Relationship

4. Click Next. This creates the first navigation function which is given a default name of getCustomerProfile().

The next stage for each navigation function is to:

- accept or change the name of the navigation function
- identify a read function contained in the navigation function (there may be more than one)
- specify parameters to invoke if parameters are supported by the underlying query function
- optionally add one or multiple where clauses

Figure 4-13 Defining the First Navigation Function

In the case of the getCustomerProfile() navigation function:

- there is only a single read function
- there are no parameters
- the where clause join elements are APPL_ORDER/CustomerID and CustomerProfile/Customer/CUSTOMER_ID

5. Click Next to define the opposite navigation function whose default name is getApplOrder().

The apparel orders data service more typically contains multiple read functions. If you select getApparelOrdersByCustID(), then you will be able to map an element (cust_id) from the opposite data service.

Notice in Figure 4-14 that the where clause you defined for the first navigation function is pre-determined and shown in read-only format.

Figure 4-14 Selecting a Parameter

6. Click Finish.

Figure 4-15 Resulting getCustomerProfile() Navigation Function

#### Testing Your Navigation Function

When you execute a navigation function in Test View, you can provide input in the form of a complex parameter such as would result from, for example, getting back a customer record. Alternatively, you could use the Test View template option to supply the appropriate parameter. See Using the XML Type to Identify Input Parameters.

### Navigation Functions in Source View

In data service Source View the navigation function is defined through a pragma and a function body. (For details see the Data Services Platform XQuery Developer's Guide).

For example, a navigation function named Payment() has a read function getPaymentList().

The navigation function appears as:

>     declare function ns1:getCustomer($arg as element(ns0:APPL_ORDER)) as element(ns15:PROFILE)* {
>         for $b in ns16:getCustomerByCustID($arg/CustomerID)
>     return $b
>     };

A key element in understanding this function is in the namespace ns15 which imports the schema that models the XML type, `PAYMENTList.xsd`. The namespace is defined as:

>     import schema namespace ns15="urn:retailerType" at
>     	  "ld:DataServices/RTLServices/schemas/Profile.xsd";

Note: If you modify a role name in the pragma of your data service, and that relationship exists in any model diagram, then you will need to similarly modify the role name in any model diagrams in which the relationship appears. Otherwise the relationship will become invalid.

## Working with Logical Data Service XML Types

Read functions associated with data services return information in the shape of the data service's XML type.

Note: Logical data services are built upon physical data services which in turn represent an underlying physical data source. Physical data service are created by importing metadata on a physical source and updated through synchronization. The schema file or XML type generated by this process should never be modified either in DSP or externally. Doing so risks invalidating your data service and dependent logical data services. (If you need to modify a data service based on a single source it is a simple matter to create a logical data service based on that one source.)

### Associating an XML Type

You can add or replace an XML type that has been associated with an data service using a browser. Your type must be located in the your application file structure.

#### Selecting a Global Element

If the schema you select has more than one global element, a dialog allows you to choose the global element you want to use.

Figure 4-16 Select Global Element Dialog Box

### Editing an XML Type

You can also edit an XML type. Several XML type right-click menu options are available (Table 4-17).

Warning: Editing changes to an XML types in Design View immediately modify the schema file upon which the XML type is based. Such changes cannot be reversed through the Undo command. For this reason, XML types should be modified carefully, with adequate backup in case you need to revert to the original version.

Table 4-17 Right-click XML Type Editing Options

Option | Purpose
--- | ---
Add Child | Adds a child element to the currently selected element. Available sub-menu options include special-purpose schema elements Choice and All.
Add Sibling | Adds a sibling element to the currently selected element. Available sub-menu options include special-purpose schema elements Sequence and Choice.
Add Attribute | Adds an attribute to the currently selected element.
Delete | Deletes the currently selected element or attribute. This option is not available for the root element of the schema.
Allow Global Types and Elements Editing | A toggle that applies to the entire schema. Schemas should be edited with care. To do so, this option must be selected.
Go to Source | Opens the XML type in the built-in schema editor.
Move Up | Moves the selected element towards the top of the schema.
Move Down | Moves the selected element towards the bottom of the schema.
Find | Finds text within the selected complex element (such as the root element).

Another option, Enable Optimistic Locking, becomes available for elements in relational-based XML types under some conditions. See Enable/Disable Optimistic Locking.

Table 4-18 identifies how various right-click options apply to different XML type elements.

Table 4-18 XML Type Editing Options / Element Matrix

Element | Add Child Element/ Choice/ All | Add Sibling Element/ Sequence/ Choice | Add Attribute | Delete | Move Up/ Move Down
--- | --- | --- | --- | --- | ---
Root element | x |  | x |  |
Complex element | x |  | x | x |
Leaf element | x | x | x | x |
Conditional element | x |  |  | x |
All element | x |  |  | x |
Sequence element | x | x | x | x |
Choice element | x | x |  | x |
Attribute |  |  |  | x |

In some cases complex type components that appear in schemas will not appear in your XML type.

Warning: XML types are based on schemas which may be used by other data services. For this reason, XML types should be modified carefully, with adequate backup in case you need to revert to the original version. Similarly, all the functions in your data service should be written to return the XML type of your data service.

#### External Editing of XML Types

In addition to the right-click menu described in Table 4-18, you can use the Go to source command to edit your schema file using WebLogic Workshop's assigned text editor.

## Creating an XML Type

You can choose to create an XML type for a new data service. Since your data service already has a name, you need only supply:

- A schema file (XSD file) name
- An XML type root element
- A target namespace

By default, the name of your data service is the same as the schema file name, the schema, and the target namespace.

Figure 4-19 Create New Schema File Dialog

Once created, you can use the data services built-in schema editor to create your schema. Alternatively, you can create a schema in a program such as XMLSpy.

# Managing Your Data Service

There are several important pre-deployment tasks you need to accomplish before you can make your data service available to client applications. This includes setting properties for your data service and it's functions.

Figure 4-20 Data Service Properties

You can use the Properties Editor (View —> Property Editor) to set or change key data service functionality including:

- Enabling or disabling update logic.
- Specifying the Java file to access for update logic.
- Creating user-defined properties, which then become available to the DSP Metadata Browser.
- Enabling or disabling caching for particular functions.
- Changing relationship settings include role name, target data service, and cardinality.

See Notable Design View Properties.

## Refactoring Data Service Functions

You can refactor data service functions insofar as they can be renamed or safely deleted. See Refactoring DSP Artifacts.

## Finding Usages of Data Services Platform artifacts

For most DSP artifacts you can quickly determine the artifacts usage through a right-click menu option. See Usages of Data Services Artifacts.

## Setting Update Options

Each data service contains a set of properties that control its update characteristics.

Note: For complete information on decomposition functions, override classes, optimistic locking settings, and other SDO-related information see Enabling SDO Data Source Updates in the Application Developer's Guide.

### Allowing Updates

You can use the Allow Update option in the Property Editor to control whether calling applications can exercise update logic associated with your data service. This is especially important in regard to relational-based data services, since update logic is automatically available unless disabled.

Set the option to True to allow update; False to prevent updates.

### Setting the Override Class

In order to update non-relational sources that are associated with your data service you need to create an update override class. In addition, you may want to overwrite built-in update logic for relational sources to apply custom logic to the update process.

Before you can set the override class, you need to develop it. The steps involved are:

- Add an appropriately named Java class to your DSP-based project.
- Within the Java file, implement the UpdateOverride interface.
- Import the required packages into your class and add a performChange() function to the class.
- Implement your processing logic.
- Associate your data service with the class.

>     <javaUpdateExit className="nameOfYourJavaClass"/>

For information on developing an override class see Enabling SDO Data Source Updates in the Application Developer's Guide.

Note: Each data service can have only one update override class. However, multiple data services can share the same update override class.

### Enable/Disable Optimistic Locking

The SDO update mechanism for relational data uses an optimistic locking policy to avoid change conflicts. With optimistic locking, the data source is not locked after the SDO client acquires the data. Later, when an updated is needed, the data in the source is compared to a copy of the data at a time when it was acquired. If there are discrepancies, the update is not committed.

Optimistic locking update policy is set for each data service. The following table lists the three optimistic locking update policy options.

Optimistic Locking Update Policy | Effect
--- | ---
Projected | Projected is the default setting. It uses a 1-to-1 mapping of elements in the SDO data graph to the data source to verify the "updateability" of the data source. This is the most complete means of verifying that an update can be completed, however if many elements are involved updates will take longer due to the greater number of fields needing to be verified.
Updated | Only fields that have changed in your SDO data graph are used to verify the changed status of the data source.
Selected Fields | Selected fields are used to validate the changed status of the data source.

For relational-based data service the Enable/Disable Optimistic Locking option becomes available for elements in its XML type when the optimistic locking property is set to Selected. (Optimistic locking policies are viewed and set through the Property Editor (Figure 4-21). For information on additional properties see Notable Design View Properties.

Figure 4-21 Data Service Allowing Updates and Optimistic Locking on Selected Fields

When active, the Selected Fields option allows you to validate optimistic locking logic prior to an update. Any number of fields can be selected through the right-click menu associated with the XML type. (If a complex element is selected, all its children are selected even though they are not so marked.)

When the Selected Fields option is picked, a right-click toggle option named Enable/Disable Optimistic Locking becomes available. Multiple elements can be selected.

Figure 4-22 Disabling Optimistic Locking Policy for a Field

In Figure 4-22 two fields are selected, PRODUCT_ID and QUANTITY.

These choices are reflected in the Source View pragma.

>     <optimisticLockingFields>
>     					 <field name="PRODUCT_ID"/>
>      <field name="QUANTITY"/>
>     </optimisticLockingFields>

For complete details on handling change conflicts based on optimistic locking policies see Enabling SDO Data Source Updates in the Application Developer's Guide.

## Adding Security Resources

Security resource settings are created at the data service level and activated at through the Data Services Platform Console. The steps involved are:

- Create as many security resources as are needed by your data service.
- Structure your query to support security resource validation.
- Assign security resources to your element through the DSP Console.
- Use Test View to validate your security policy settings.

An easy way to understand security settings is to create an example using the Shipping data service found in the DataServices/Demo/Java/Logical folder of RTLApp.

Goal. The goal is to restrict access for the East shipping region to the XML type's ShipRegion string to a particular traffic monitor named Igor.

The following section describe the steps involved.

### Create Necessary Security Resources

1. Open your data service.
2. Open the Property Editor.
3. Create a security resource by clicking the + on the Security Resource line. Any value (name) can be assigned to a security resource. In this case the name of an element in your XML type is used.

Figure 4-23 Create a Security Resource

This action add your new security resource (highlighted below) to the data service pragma in Source View.

>     (::pragma  xds <x:xds targetType="ship:ShipSource" xmlns:ship="http://Logical/ShipSource" xmlns:x="urn:annotations.ld.bea.com">
>         <creationDate>2005-11-01T15:50:28</creationDate>
>         <userDefinedView/>
>         <secureResources>
>             <secureResource>shipregion</secureResource>
>         </secureResources>
>     </x:xds>
>     ::)

### Structure Your Query To Support Security Resource Validation

In this section you use the XQuery Editor to attach your newly created security resource to the EAST group, ShipRegion element.

1. Click XQuery Editor View.
2. In the return type attach a security resource to the EAST group, ShipRegion element. Do this by right-clicking on the element to which you want to attach a security resource, then select the Make Conditional option.

Figure 4-24 Creating an If-Else Construct for East Group's ShipRegion String

3. Associate your new conditional element with the built-in fn-bea:is-access-allowed() function by clicking on the element and dragging the function into the Expression editor. The function takes two parameters: a string and the name of a data service. In this case the string exactly matches your security resource name.

Note: (For details on built-in BEA functions see the DSP XQuery Reference Guide. For details on editing expressions see Transforming Data Using XQuery Functions.)

4. Populate the function parameters by either entering the appropriate strings or dragging elements into the function placeholders.

Figure 4-25 Establishing Security Control for East Group's ShipRegion Element

5. The If-Else construct may now be read as "if access is allowed to the element return data, otherwise return nothing". In many cases it is appropriate to return the fact that access is not allowed. This can be accomplished by setting the expression associated with the Else side of the conditional to "N/A" (not available).

In Source View your conditional is rendered as an XQuery if-else statement.

>     if (fn:upper-case($SourceRegion) eq 'EAST') then
>               (
>                 for $ShipSource1 in ns10:getShipSource1()/SHIPPING
>                 where $ShipSource1/ShipSource eq $SourceState
>                   and $ShipSource1/ShipDest eq $DestState
>                 return
>                 <SHIPPING DataLineage?="{'EAST Shipping Source'}">

>              ...

>            <ShipPrice>{fn:data($ShipSource1/ShipPrice)}</ShipPrice>
>                     {
>                     if (fn-bea:is-access-allowed("shipregion", "ld:DataServices/Demo/Java/Logical/Shipping")) then
>                     	<ShipRegion>{fn:data($ShipSource1/ShipRegion)}</ShipRegion>
>                     else
>                     	<ShipRegion>{"N/A"}</ShipRegion>
>                     }
>                     <ShipTime>{fn:data($ShipSource1/ShipTime)}</ShipTime>
>                 </SHIPPING>

1. Build your project. This deploys your new security settings to the server.

### Assign Security Resources Through the DSP Console

The next steps involve the Data Services Platform Console (see Securing Data Service Platform Resources in the DSP Administration Guide for complete details).

1. Sign into the DSP Console. For the RTLApp sample the user name and password are both `weblogic'.

Note: Unless a secured resource has been marked as available to user weblogic or some group that user weblogic is a member of, it will not be available.

2. Find the heading Search Metadata. Click on the Search ldplatform (the RTLApp sample domain server).
3. In the data service name field search for "shipping".
4. In the Search Results click on the Shipping.ds name link to view the various administrative, caching, auditing, metadata search, and security options available to the data service.
5. Click the Security tab.

Figure 4-26 Security Policies Associated with the RTLApp's Shipping Data Service

6. Since you created a security resource named shipregion for your data service, it appears as an available resource name. Now security policies must be associated with the resource. Click the Action icon.
7. In the Administration Policies pane select the User name of the caller policy condition, then click Add.
8. A dialog box appears where you can enter the name of the user.

Figure 4-27 Associating a User Name with a Security Resource

9. Click Apply.

### Validating Security Policies Through Test View

Once security policies are established, they should be tested.

1. With the Shipping data service selected click the Test View tab.
2. The getShippingSource() function requires a source state and a destination state. (Valid states are shown in the `Examples.txt` source file which is located in the Demo/Java/Logical folder.)
3. Enter MA as the source state and VA as the destination, then click Execute.

Figure 4-28 Validating that the ShipRegion Element is Secured

4. Notice that rather than returning the region, the Else string N/A is returned. This is because the registered user of Test View is user weblogic, not user Igor.

## Caching Functions

For each function in your data service, the Allow Caching option can be set to True or False. If False, results from executing your query function cannot be cached. If True, results from earlier invocations of your function can be cached if cache for that function is enabled through the Data Services Platform Console. In other words, in order to cache a function it must be Enabled:True in its data service and also enabled through the DSP Console. For details on enabling cache for a function as well as setting the cache's TTL (time-to-live) see the DSP Administration Guide.

#### Caching Considerations

There are several things to keep in mind when considering whether to enable caching for a particular function:

- If the data accessed by your function is updated frequently, the function is not a good candidate for caching.
- Generally speaking, you should only enable cache to data service functions that have parameters. Since relational tables do not, by definition, have parameters, the cache for such tables should generally not be enabled.

#### Setting Caching Policy for a Function

To inspect or set the Allowed caching policy for a particular read function in your data service, click on the arrow to the left of the name of the function, then set its caching policy through the Properties Editor.

Figure 4-29 Click Arrow to the Left of a Function Name to Inspect or Set Its Caching Policy

You need to build your application in order for cache policy changes effective.

Note: When a cache policy of Enabled:False is set for a function it cannot be overridden through the Data Services Platform Console.

## Notable Design View Properties

The following table identifies notable Data Services Platform Design View properties.

Table 4-30 Notable Design View Properties

Focus | Property | Settings | Comments
--- | --- | --- | ---
Data service | Name | Editable | Must end in `.ds`
| Description | Text | Optional
| Author | Text | Optional
| Creation Date | Non-editable |
| Type | URI to optional XML type | Also known as XML type.
| DS Update : Allow Update | True / False | Allows calling applications to execute the data service's update logic.
| DS Update : Decomposition Function | Selectable for logical data services with more than one read functions. | Identifies the function used for decomposition of the data service. In the case of physical data services the decomposition function is pre-defined by the source metadata. For logical data services, however, you can change the default decomposition function to another read function in your data service. For additional information on decomposition functions see Leveraging Data Service Reusability.
| DS Update : Override Class | Optional and editable | Identifies a external Java class that provides custom update logic.
| Optimistic Locking Fields | Projected / Updated / Selected Fields | Applies only to relational-based data services.
| Security Resources | Any number of name:value pairs. | See Adding Security Resources.
| Prefix bindings | Any valid, non-conflicting prefix can be entered for namespaces defined in the data service. | See Refactoring DSP Artifacts.
| User-defined Properties | Optional and editable | Create any number of name/value pairs.
Data Service Read and Private Functions and Procedures | Name | Editable |
| Function type | Selectable (read or private) | Selectable for read function or private functions; not selectable for procedures.
| Cache enabled | True / False | Enables cache for the function.
| User Defined Properties | Optional and editable | Create any number of name/value pairs.
XML type | Root: Name | Editable | Typically same name as the data service without the file's extension.
| Root: Is Referenced | False | Read only. For the root element the Is Referenced property is always false as it is always a global element in the schema.
| Root: Type | <blank> or named type | Blank if the root element is an anonymous type; otherwise named type is shown
| Element: Is Referenced | True / False | Read only. Identifies any elements that are imported into the current function. In source this appears as ref="element".
| Element: Type | XML type | Examples: xs:int; retailer: CUSTOMER_VIEW
| Element: Min Occurs | 1, 0, or n |
| Element: Max Occurs | 1, 0, or n |
| Element: Native Type | Data type | Available only for physical data. Example: VARCHAR
| Element: Native Size | Size of the data | Available only for physical data. Example: 10
| Primary key: AutoNumber | <blank>, identity, sequence, or userComputed | This and the Sequence Object Name option appear for elements representing primary keys in relational-based physical data services. Autonumber can be used to provide a value for a database primary key. Leaving the field blank means you will provide a value for the primary key. The identity option pertains to IBM DB2, Sybase, SQL Server, and MySQL. In this case the database will provide a value for the primary key. Sequence objects are available for DB2 and Oracle. You must provide a sequence object name. User computed is a notational flag indicating that the primary key information has been provided to the database through your SDO custom update override class. Note: It is not necessary to set this flag in order for the update override computed primary key logic to be used.
| Primary key: Sequence Object Name |  | If sequence is selected in the AutoNumber property (above), then the sequence object name must be supplied
Related Data Service | Role Name | Editable | Also changes the role name shown in a model diagram.
| Related Data Service | Path to the related data service |
| Min Occurs | 1, 0, or n |
| Max Occurs | 1, 0, or n |
| Opposite Role Name | Editable | Also changes the role name shown in the model diagram.
Relationship Read Function | Name | Editable |
| Cache | True / False | Enables cache for the function.
| Return type | Non-editable | Always navigation type.
| User Defined Properties | Editable | Create any number of name/value pairs.
XML File Library (XFL) | Name | Editable | Must end in `.xfl`
| Prefix bindings | Any valid, non-conflicting prefix can be entered for namespaces defined in the data service. | See Refactoring DSP Artifacts.
XFL Functions |  |  |

###