eDocs Home > BEA AquaLogic Data Services Platform Documentation > Data Services Developer's Guide > Contents

How To Create Logical Data Service Keys

This topic describes how to create a key for a logical data service.

Overview

A logical data service key uniquely identifies a data record the logical service defines. Because a logical service combines data from various physical and logical services, its key can combine or be different from the keys defined on underlying data sources.

For example, you might have a logical data service with a flat return type that combines data from two relational tables, CUSTOMER and ORDER. These tables have keys CUSTOMER_ID and ORDER_ID, respectively. In your logical data service, each data record is a unique combination of Customer and Order, so you create a composite key that combines CUSTOMER_ID and ORDER_ID.

Create procedures return a key to identify the data record that was inserted. Update and Delete procedures act on the data record the key identifies. A logical data service can have one key, although you can have multiple key schema files from which you select the key. You can have ALDSP auto-generate the key, choose the elements you want in the key, or select an available schema (XSD) file to use for the key. The key definition requires specific knowledge of your data and the update map the service uses.

You can create a key for any logical data service that has a primary Read function. Once you create the key, you can view it in an update map and test it.

Generate a Key

For an auto-generated key, ALDSP uses elements from the return type of the primary Read function that are designated as keys in the underlying data sources and have single (1..1) cardinality.

To auto-generate the key:

1. Be sure the logical data service has a primary Read function.
2. Open the logical data service in Studio, and click the Overview tab.
3. Right-click in the service name bar, or at the left or right of the screen, and choose Manage Key.
4. Select Generate a New Schema.
5. Accept the default key name, or give your key a name ending in .xsd.
6. Click Next.
7. Select Auto Generate the Key, then click Finish.

Auto-Generating a Logical Data Service Key

You can now use the key as an argument or return type to an update map procedure, such as a Create, Update, or Delete procedure.

If you create a key, then delete it and create another one, you need to edit the signature of your Create procedure to return the new key:

Select Elements for a Key

When you select elements for a key, you can add any element with single (1..1) or zero (0..1) cardinality, whether or not it is a key element in the underlying data source. An element with zero cardinality is optional and might contain null values, but you can use it as a key element. This allows you to create a wider variety of keys.

For example, you might have two data sources, one using a Social Security Number to identify records, and the other, a tax identification number. Your logical data service might have a return type that joins the two sources, so that a data record has either a social security number or a tax ID number. In the return type, both the social security number and the tax ID number are optional. The key can use either element to identify the record.

You cannot select an element that has multiple (0..m or 1..m) cardinality to be part of a key.

To create a key with elements that you select:

1. Be sure the logical data service has a primary Read function.
2. Open the logical data service in Studio.
3. Click the Overview tab. 
4. Right-click in the service name bar, or the left or right of the screen, and choose Manage Keys.
5. Click Generate a New Schema.
6. Give your key schema a name ending in .xsd. 
7. Click Manually select the fields that make up the key.
8. Select the key fields you want, then click Finish.

Selecting Elements for  a Key

Select a Key Schema File

You can also select an existing schema (XSD) file to use as the key:

1. Be sure the logical data service has a primary Read function.
2. Open the logical data service in Studio
3. Click the Overview tab.
4. Right-click in the service name bar, or the left or right of the screen, and choose Manage Key.
5. Click Select an existing schema type, then Browse.
   The Manage Keys dialog shows you the key schema's global element and selector element.
6. Click Finish.

The schema in the Overview tab now displays a key icon next to the current key element or elements.

Selecting the Key Schema

View and Map a Key

Once you create the key (whether by auto-generating, identifying key fields, or selecting a key schema file), you can see the key elements in the service's update map, at the lower left.

Viewing the Key in the Update Map

The Return Key block represents the key elements a Create procedure returns when a new data record is added. In most cases, the key fields are automatically mapped to elements in the data sources on the left. If they are not mapped, you can add a mapping.

1. Locate the Update block on the left that contains the key element.
2. Drag from the key element in the Update block to the key element in the Return Key block.

Mapping a Key Element from an Update Block to the Return Key

Map the key element from an update block on the left, not from the return type on the right. If you map the key from the return type on the right, you allow the key value to be updated from data a user enters.

Once the key element is mapped, you can test it (preferably using sample data):

1. Click the Test tab.
2. At Select operation, choose one of the service's Create procedures.
3. Enter data in the XML template in the Parameters box.
4. Click Run.

The key value is returned in the Result box:

You can also view the key schema file by locating the key in the Project Explorer, right-clicking, and choosing an XML editor to open the file. A key schema looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="ld:logical/CustomerOrder" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="CustomersAndOrders_KEY">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CUSTOMER_ID" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

In the key schema, all elements must be in the same namespace as the root element. In the previous example, the namespace of the root element is:

If you have key schema files from a previous version of ALDSP that you want to reuse, be sure that all elements within the schema are in the same namespace.

See Also

Concepts

• Data Service Keys