When the business object handler obtains an Update verb from the
request business object, it must ensure that an existing
application entity, whose type is indicated by the business object
definition, is updated, as follows:
- For a flat business object,
the Update verb indicates that the data in the specified entity
must be modified as necessary until the application entity exactly
matches the request business object.
- For a hierarchical business
object, the Update verb indicates that updates the application
entity must be updated to match the entire business object
hierarchy. To do this, the connector might need to create, update,
and delete application entities:
- If child entities exist in the application, they are modified
as needed.
- Any child business objects contained in the hierarchical
business object that do not have corresponding entities in
the application are added to the application.
- Any child entities that exist in the application but are
not contained in the business object are deleted from the
application.
- Note:
- For a table-based application, the entire application entity
must be updated in the
application database, usually as a new row to the database table
associated with the business object definition of the request
business object.
This section provides the following information to help process
an Update verb:
- Note:
- You can modularize your business object handler so that each
supported verb is handled in a separate Java method. If you follow
this structure, an Update method handles processing for the Update
verb.
The following steps outline the standard processing for an
Update verb:
- Create a new business object of the same type as the request
business object. This new business object is the response business object, which will hold
the retrieved copy of the request business object.
- Retrieve a copy of the request
business object from the application.
Recursively retrieve the data for the entire entity from the
application using the primary keys from the request business
object:
- For a flat business object, retrieve the single application
entity.
- For a hierarchical business object, use the Retrieve operation
to descend into the application business object, expanding all
paths in the business object hierarchy.
- Place the retrieved data in the response business object. This
response business object is now a representation of the current
state of the entity in the application.
The Update operation can now compare the two hierarchical
business objects and update the application entity
appropriately.
- Update the simple attributes in the application entity to
correspond to the top-level source business object.
- Compare the response business object (created in step 2) with the request business object.
Perform this comparison down to the lowest level of the business
object hierarchy.
Recursively update the children of the top-level business object
following these rules:
- If a child business object is present in both the
response business object and the request business object,
recursively update the child by performing the Update
operation.
- If a child business object is present in the request business
object but not in the response business object, recursively
create the child by performing the Create operation.
- If a child business object is not present in the request
business object but is present in the response business object,
recursively delete the child using either the Delete operation
(physical) or a logical delete, depending on the functionality of
the connector and the application. For more information on logical
deletes, see "Implications of
business objects representing logical Delete events".
- Note:
- Only the existence or non-existence of the child objects are
compared, not the attributes of the child business
objects.
If the connector's application supports logical delete,
the connector recursively retrieves the complete business object
hierarchy; then the Update operation sets status attributes and
recursively updates the status of the children.
- Note:
- The Update operation should fail if an application entity does
not exist for any
foreign key (Foreign Key is set to true) referenced in the request
business object. The connector should verify that the foreign key
is a valid key (it references an existing application entity). If
the foreign key is invalid, the Update operation should return
FAIL. A foreign key is assumed
to be present in the application, and the connector should
never try to create an application object marked as a
foreign key.
Figure 34 shows a set of
associated application entities that represent a customer in the
application database. The entities contain customer, address,
phone, and customer profile data. Note that the sample customer,
Acme Construction, has no phone number in the database.
Figure 34. Customer entities before
Update request

Assume that an integration broker sends an update request that
consists of the request business object as shown in Figure 35..
Figure 35. Customer request business
object for an Update

This request business object indicates that the Acme
Construction customer has undergone the changes listed in Table 38..
Table 38. Updates to Acme Construction
in the Request business object
Update made to
Acme Construction |
Representation
in request business object |
Acquired a
new phone number |
The child
business object for the PhoneArray attribute (Phone object A) has a
Create verb. |
Moved to new
offices in Denver and Altos |
Two child
business objects (Address objects A and B) exist in the
AddressArray attribute, each with an Update verb. |
Closed the
office in Akron |
No child
business object exists in the AddressArray attribute for the Akron
address. |
Changed the
name of the contact person |
The child
business object for the CustProfileArray attribute (CustProfile
object A) has an Update verb. |
Your connector's task is to keep the application database for
this destination application synchronized with the source
application. Therefore, to respond to this request, the connector
would need to perform the following tasks as part of its Update
operation:
- Update any columns in Customer table that have updated
values in the corresponding simple attributes of the Customer
business object.
- Update the rows in the Address table that correspond
to Address objects A and B. Update the columns in each of these
rows with any new values from the corresponding simple attributes
in the appropriate Address object. In this case, the
Street column has changed for the Denver and Altos
offices.
- Delete the row in the Address table that corresponds
to the Akron address.
- Update the Contact column of the
CustomerProfile table to the value of the corresponding
simple attribute in the CustProfile object A business object.
- Create a row in the Phone table with column values
from the simple attributes of the Phone object A business object.
Make sure that the CustID column of this new row is
created with the foreign-key value that identifies the appropriate
Customer row (22).
Figure 36 shows the set
of associated application entities that represent a customer after
the Update operation has completed.
Figure 36. Customer entities after
Update request

If your application supports physical delete, but an integration
broker sends requests from a source application that supports only
logical delete, you might need to handle a business object that
represents a logical delete request. Connectors for applications
that perform logical delete operations, where an entity is
marked as deleted by updating a status value, should handle logical
deletes in the Update method. A system view of this implementation
is as follows:
- Events that represent the deletion of data in the source
application should be sent as application-specific business objects
with the Delete verb. Similarly, maps on the source application
side should set the verb of generic business objects to
Delete.
- On the destination side, maps for connectors supporting logical
delete applications can transform Delete verbs in generic business
objects to Update verbs in application-specific business objects.
Business object attributes representing entity status values can be
set to the inactive status.
In this way, a connector representing a logical delete
application receives an application-specific business object with
an Update verb and the status value marked appropriately.
For example, assume that a source application entity has been
updated to look like the business object representation in Figure 37.. Components in the
source application entity have been updated, created, and
deleted.
Figure 37. Updated entity in the source
application

If the source application connector has implemented event
notification as recommended in Event notification,
deleted child business objects are not present in the business
object hierarchy, and the business object simply contains the
updated and new child business objects.
An example of a business object representing an Update request
might look like Figure 38..
In this figure, the parent object is set to update, and all
entities that have been deleted are no longer present in the
business object hierarchy.
Figure 38. Update request business
object from a physical-delete connector

In this case, the connector compares the source and destination
business objects and deletes the entities that are not present in
the source business object.
However, if the source application supports logical delete, the
source connector might send a business object with deletes tagged
as updates and status attribute values set to an inactive value.
This business object might look like Figure 39,, where updates that are
delete operations are identified by "[D]".
Figure 39. Update request business
object from a logical-delete connector

There are several ways to handle a source business object that
represents a logical delete request:
- Implement mapping to examine the status of child business
objects. If the status of a particular child business object is
inactive, the business object can be removed in mapping.
- Implement the Update operation to determine whether an update
operation is actually a delete operation. In a logical delete
source application, an entity may be marked as active or inactive
by a status value. In the source's application-specific business
objects, the status value is usually an attribute. Although
entities in an application that supports physical delete might not
include status information, you can extend your
application-specific business objects to include status
information.
- Extend a business object by adding an additional status
attribute or by overloading an existing attribute with a status
value. When the Update operation receives a request, it can check
the status attribute. If it is set to the inactive value, the
operation is really a delete. The Update operation can then set the
business object verb to Delete and call the Delete operation to
handle deleted child business objects.
The Update operation should return one of the outcome-status
values shown in Table
39..
Table 39. possible outcome status for
Java Update verb processing
Update
condition |
Java outcome
status |
If the
application entity exists, the Update operation:
- modifies the data in the application entity
- returns a "Success" outcome status
|
SUCCEED
|
If a row or
entity does not exist, the Update operation:
- creates the application entity
- returns the "Value Changed" outcome status to indicate that the
connector has changed the business object
|
VALCHANGE
|
If the Update
operation is unable to create the application entity, it:
- fills a return-status descriptor with information about the
cause of the update error
- returns a "Fail" outcome status
|
FAIL
|
If any object
identified as a foreign key is missing from the application, the
Update operation:
- fills a return-status descriptor with information about the
cause of the update error
- returns a "Fail" outcome status
|
FAIL
|
- Note:
- When the connector framework receives the VALCHANGE outcome
status, it includes a business object in its response to
InterChange Server. For more information, see Sending the verb-processing
response."Sending the verb-processing response" on page
179.
