The Integration Repository can define five types of operations that allow Oracle Commerce Platform repository items to access data in remote systems:
executeQuery
There are four possibilities here:
Always query against the local repository. For example, you may decide that updates to profiles need to be sent to a remote system, but queries of that data will always be done locally.
Always query against the remote system. For example, you may want the data to remain in the remote system with no persistent storage in Dynamo.
Check the local repository first, then check the remote system.
Check the remote system first, then Dynamo.
If there is a Command associated with the query operation then the remote system is queried. If no Command is configured, then the local repository is queried.
When you want to execute a query against the Integration Repository, your code will look something like this:
Repository rep = getRepository(getMyRepository()); RepositoryView view = rep.getView(getMyView()); QueryBuilder builder = view.getQueryBuilder(); Query query = builder.createSomeQuery(MyQueryExpression); RepositoryItem[] results = view.executeQuery(query);
There is no Integration Repository specific code in any of this. This is because you build queries with the Integration Repository in exactly the same way that you would build queries with the SQL repository. This also means that you can use RQL. You can use standard query builder calls, so the Query object that gets generated is a standard Query object from the atg.repository.query package.
This real difference is in the RepositoryView. The Integration Framework uses a subclass named IntegrationRepositoryView. This class provides an implementation of executeUncachedQuery that is expected to call the query Command. There needs to be a subclass of IntegrationRepositoryView for each remote system you want to query. This subclass is responsible for translating between the Oracle Commerce Platform Query and the query format expected by the remote system.
A query Command will receive whatever input is created by the createQueryCommandInput method of your IntegrationRepositoryView.
The IntegrationRepositoryView.processResults method is responsible for translating between the remote data format and our repository items.
getItem
The getItem operation returns the value from the local repository. If there is no result, or if the entry in the local repository is invalid, the getItem operation updates the local repository with the results returned by the execution on the remote system of the Command associated with the getItem operation.
This operation uses the IntegrationRepositoryItemDescriptor.getRemoteItem() method. Commands executed for get-item will receive whatever input is created by IntegrationRepositoryTools.createGetCommandInput(). By default this is a map of the external ID property name to the value of the external ID. If you require a more complex command input, extend IntegrationRepositoryTools and override the createGetCommandInput() method.
If the item descriptor’s use-external-id attribute is true, then the given local repository item ID is identical to the remote ID. If this attribute is false, then the remote ID must be retrieved from the local item (using the item descriptor’s external-id-property).
If getRemoteItem throws an exception, then if the item descriptor’s use-local-on-failure attribute is true, the operation returns the value from the local repository. Otherwise, the exception is passed on.
updateItem
The updateItem operation updates the values of the repository item’s properties both in the local repository and the remote system. The update is handled transactionally, so that if the update of the remote system fails, the change to the local value will not occur.
This operation uses the IntegrationRepositoryItemDescriptor.updateRemoteItem() method. If the Integration Repository item descriptor defines a mapping file for the updateItem operation, then the updateItem operation creates a MappingRepositoryItem. If the changed-properties-only attribute is true, then the updateItem operation creates a ChangedPropertyBean. Otherwise, the IntegrationRepositoryItem is used.
The input for the updateItem Command is either the IntegrationRepositoryItem, the MappingRepositoryItem, or the ChangedPropertyBean as appropriate. It returns a CommandResult. The updateItem operation checks if there is an external ID in the CommandResult returned by the updateItem Command. If there is, the updateItem operation updates the external ID property of the local repository item with the value.
If update-local-with-result is set to true, then the Integration Repository looks in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item.
If the updateRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the updateItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
updateItem and Derived Properties
If your underlying local repository uses the derived properties feature of the SQL repository and you are using the changed-properties-only attribute set to true, then you should define a derived-properties element to specify how the derived properties are handled. The derived-properties element is a container for a list of derived properties mapped to some property that is used in the derivation. It ensures that if the value of a property that is one of the derivation expressions of a derived property is changed, the Integration Repository treats the derived property itself as changed as well.
The derived-properties element can optionally be used as a child element of an update-item tag. It is a container for one or more property elements, each of which has a name attribute and a referenced-property attribute. The name attribute is the name of a property that can be derived from the referenced-property. The name attribute and referenced-property attribute must both be valid property names defined within the given item descriptor.
If changed-properties-only="true" in the update-item element, then whenever the referenced-property is sent in the update command, the name property will be as well. For example, suppose you have a property named remoteAddress that can be derived from a property named businessAddress. By including this derived-properties element in the update-item element, then whenever the businessAddress property is included as a changed property, the remoteAddress property will also be included as a changed property:
<derived-properties>
<property name="remoteAddress"
referenced-property="businessAddress"/>
</derived-properties>
If you do not configure the derived-properties element for any derived properties in your item, then a change to a derived property’s expression will not cause the derived property itself to appear as a changed property. See SQL Repository Data Models: Derived Properties in the Repository Guide for more information about derived properties.
addItem
The addItem operation adds the item to the local repository and to the remote system. If the addItem operation fails on the remote system, then the item will not be added to the local system. Since the item is being newly added to the remote system, it is impossible to know in advance what value of the external ID is. The addItem operation attempts to set the external ID property with the result of the addItem Command. If the use-external-id attribute is true, then a change to the ID results in a clone of the item passed into this operation.
This operation uses the IntegrationRepositoryItemDescriptor.addRemoteItem() method. The input for add-item Commands is the RepositoryItem being added. If the Integration Repository item descriptor defines a mapping file, then the addItem operation creates a MappingRepositoryItem. Otherwise, the IntegrationRepositoryItem is used.
When the addItem Command returns successfully from the remote system, the addItem operation checks if there is an external ID in the CommandResult. If there is, the addItem operation updates the external ID property in the local repository with the ID value. If update-local-with-result is set to true, then the Integration Repository looks in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item. If the item was cloned, the original item is removed and the new item is returned.
If the addRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the addItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
removeItem
The removeItem operation removes the item from the local repository and from the remote system. This operation uses the IntegrationRepositoryItemDescriptor.removeRemoteItem() method. If there is a mapping file defined in the item descriptor, the target name of the external ID property is used. If the useExternalId is false, then the given ID is the local repository item ID.
The input for commands executed for remove-item is whatever input is created by IntegrationRepositoryTools.createRemoveCommandInput(). By default this is a map of the external ID property name to the value of the external ID. If you require a more complex command input, extend IntegrationRepositoryTools and override the createRemoveCommandInput() method.
If the remove operation in the remote system fails, the local item will not be removed. If the removeRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the removeItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
