Understanding Update Maps This page last changed on Nov 29, 2008. .stickable, h1, h2, h3, h4, h5 false true Show Sticky notes Hide Sticky notes Save Cancel Oracle Data Service Integrator Documentation > Data Services Developer's Guide # 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.
| Oracle XQuery Scripting Extension (XQSE)
Oracle Data Service Integrator 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). Example: a simple update map
| In this overview, as a running example we use an update map for a data service that joins together customers and orders. The image to the left shows the update map for the data service (CustomerOrders.ds). The orange arrow identifies the location of the "Update Map" tab.
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. Example: the target box
| The image to the left shows the update map for the data service CustomerOrders.ds. The target box is identified by the orange rectangle on the right. The procedure icons are in the upper-right corner of the target box. In this case they all contain a green check which indicates that the create, update, and delete update map procedures will function correctly. The input type to the procedures is shown below the procedure icons.
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. Example: for each blocks
| The image to the left shows the update map for the data service CustomerOrders.ds. The two orange arrows identify the two for each blocks in the map. The blocks are grey and have the title "For Each" followed by the variable name. The second for each block titled "For Each $order" is currently selected (to select a for each block, click on it). The orange rectangle identifies the properties of the currently selected for each block. In this case we see that it defines the variable `$order` which iterates over the sequence `$customer/order`. `$customer` is a variable defined by the upper 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 (also referred to as the key 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`. When an update block results in the underlying update or delete procedure being invoked, the output variable will bind to the empty sequence. 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 as siblings within the same for-each block, it may be desirable to specify dependencies between them (e.g., due to referential constraints), so an update block can also include a list of dependencies. If update block `A` depends on update block `B`, update block `B` will execute before update block `A` in the case of a create or update operation (and in the opposite order in the case of a delete). Dependencies between update blocks that are not within the same for each block are not necessary, as the execution of an update map is implicitly outside-in. 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. Example: update blocks
| The images to the left show the update map for the data service CustomerOrders.ds. In the first image, the two orange arrows identify the two update blocks in the map. One update map is for the source data service `CUSTOMER` and the other is for `ORDERS`. In this case, the `ORDERS` update block is selected and its details are identified by the orange rectangle (select an update block by clicking on it). We can see that the output variable for this update operation is `$ORDERS_key`. The condition is set to `fn-bea:value($order/status) eq "OPEN"` which means that this update block will only be executed when the input element `status` has the value `"OPEN"`. `$order` is a variable that is defined by the for each block containing the update block ("For Each $order").
| In the second image, the orange arrow identifies the `ORDER_TOTAL` element of the `ORDERS` update block. The orange rectangle identifies the mapping expression (`$fn-bea:value($order/total)`) for `ORDER_TOTAL` which is displayed because `ORDER_TOTAL` is currently selected. The `ORDER_TOTAL` element will receive the value of the `total` element when the source data service procedure is invoked.
### 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. Example: the return key block
| The image to the left shows the update map for the data service CustomerOrders.ds. The orange arrow identifies the key block in the update map. The key specified for the CustomerOrders data service is the element `CID` so the key block constructs the `CID` element to be returned and uses the output variable of the `CUSTOMER` update block to get the value.
### Customization Oracle Data Service Integrator 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. There are several 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 Example
| The image to the left shows the update map for the data service CustomerOrders.ds. The orange arrow identifies the "customized" symbol that appears after something in the update map has been changed. In this case, it is the mapping expression for `ORDER_STATUS` that has been modified.
Clicking the Customized icon and choosing View Customization from the menu displays a dialog showing the current customizations to the update map, including the enabling of update blocks, any conditions that have been set, and any changes to the mappings. This can help you to identify potential problems with the update map that might occur after you make a change to the primary read function, for example. If a problem has been identified, clicking OK accepts the correction and generates a new update map. Note that in previous versions of Oracle Data Service Integrator, customizing the update map and then changing the primary read function resulted in the update map no longer being automatically regenerated. In the current version of Oracle Data Service Integrator, the update map is updated incrementally after customizations, as required. Attachments: Customer Orders Update Map.png (image/png) The Target Box.png (image/png) Hover Over Procedure Icon.png (image/png) Red Update.png (image/png) Yellow Update.png (image/png) Green Update.png (image/png) Green Delete.png (image/png) Green Create.png (image/png) For Each Blocks.png (image/png) Update Blocks.png (image/png) The Return Key Block.png (image/png) Update Block Element.png (image/png) Customize.png (image/png) cust.png (image/png)

Document generated by Confluence on Jan 13, 2009 15:57