Understanding Update Maps

An update map allows you to easily update your logical entity data service without having to write Java or XQSE code. This overview provides a foundation for understanding what an update map is and how you can use one.

BEA XQuery Scripting Extension (XQSE)

ALDSP generates a default update map automatically when you create a logical entity data service with a primary read function. You can see the update map associated with a data service by clicking the "Update Map" tab at the bottom of the screen (see the example that follows; click to enlarge image).

An update map procedure is a create, update, or delete procedure that is implemented by an update map. The update map maps values from the input to the update map procedure to the inputs of the procedures in the underlying data services. These underlying data services that the logical entity data service is composed of are referred to as the source data services. In the previous example, the input is mapped to the two source data services CUSTOMER and ORDERS. The blue arrows in the update map show how the values are mapped.

A logical entity data service has a target type that describes the entity that the data service is about. All read functions in the data service must return instances of the target type and all update map procedures must accept instances of the target type as input. For example, say that we have an entity data service about customers. The read functions of this data service must return customers and update map procedures must take customers as input.

The Target Box

The target box displays the data type of the input to the update map procedures and the procedure icons. There is always exactly one target block in an update map and it is displayed on the right.

The input type
The input type (or, target type) is the type of the data that is passed to the update map procedures. Elements and attributes from the input type are mapped to the update blocks on the left.

Procedure icons
The create , update , and delete procedure icons indicate the status of the corresponding update map procedures. They appear in the upper-right corner of the target box. Each icon may have a green check, a yellow exclamation or a red 'X'. A green check indicates that the update map is fully capable of implementing the procedure. A yellow exclamation indicates that you can invoke the procedure, but there may be problems at runtime. A red 'X' indicates there is a serious problem that needs to be addressed. Any time that there is a red 'X' or a yellow exclamation on the icon, you can hover the mouse pointer over the icon to get a tool tip providing more information (see the image below).

For Each Blocks

A for each block loops over elements in the input to the update map procedure. A for each block is associated with a variable and a path expression. The path expression defines the sequence to iterate over and the variable binds to elements in the sequence. The variable may be referenced by expressions inside the for each block.

Update Blocks

An update block invokes the primary create, update, or delete procedure of a source data service. It will invoke a procedure every iteration of the for each block that contains it. The contents of the update block represent the type of the input given to the procedure. Each element and attribute in the update block is assigned a mapping expression that determines what its value will be when the procedure is invoked. You can select an element or attribute to view or change the expression that determines what value it receives when the procedure is invoked (see the example below).

Procedure icons
Like the target box, an update block also has a procedure status icon. Here the icons indicate the ability of the update block to propagate creates, updates, and deletes to the underlying data service. Otherwise, the meaning of the icons is the same as it is for the target box.

Output variable
A primary create procedure may return a key. If the update block invokes a primary create procedure, it will bind the returned key to the output variable. The purpose of having the output variable available is for cases when the key value is generated automatically by an external source but is not part of the input. For example, your source data service is a wrapper for a customers relational database table. Say that the key of this table is an attribute CUSTOMER_ID which is an auto-generated number. If you are inserting a customer and some orders at the same time, you may need the auto-generated value for CUSTOMER_ID to pass to the input of the create procedure for ORDERS.

Condition
An update block can optionally have a condition. The condition is a Boolean expression that determines if the update block should be invoked or not. If there is no condition, then the update block will always be invoked (see the example below).

Dependencies
When two or more update blocks appear within the same for each block, it may be desirable to specify dependencies between them. If update block A depends on update block B, it means that update block B will execute before update block A. Dependencies between update blocks that are not within the same for each block are not necessary as the order is implicit (the outermost update block executes first).

Disabling an update block
An update block can be disabled so that it will never be invoked at runtime. You can disable an update block by right clicking on it and selecting "Disable" The update block should then appear yellow instead of white to indicate that it has been disabled. Disabling an update block is effectively the same as adding a condition that is always false.

The Return Key Block

The key block describes what will be returned by the update map create procedure. If the data service does not have a key specified, then there will not be a key block and there will never be more than one key block for an update map.

Customization

ALDSP generates a default update map automatically when you create a logical entity data service with a primary read function. This default update map is generated based on the primary read function of the data service. As you change the primary read function, the update map will be regenerated automatically. However, if you customize (change) the update map then it will no longer be regenerated. In other words, a customized update map will no longer change along with the primary read function.

There are many different ways to customize an update map. See the following topics for more information:
Change a Mapping
Remove a Mapping
Revert Customizations
Edit XQuery Expressions
Add a Condition to an update block