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.