The Integration Repository consists of a set of item descriptors. Each item is queryable through a RepositoryView using a QueryBuilder. Each item descriptor is associated with a particular Command or set of Commands. One of these Commands returns results that are converted to repository items of the given item descriptor. Other Commands are used for updating or deleting values in the remote system.

The Integration Repository includes extensions to, or implementations of, the following repository classes. Each of these classes is in the atg.adapter.integrations package.

IntegrationRepository extends atg.repository.RepositoryImpl
IntegrationRepositoryItemDescriptor extends
IntegrationRepositoryItem implements atg.repository.RepositoryItem,
ChangedPropertyBean implements atg.repository.RepositoryItem,
atg.repository.databinding.MappingRepositoryItem implements
atg.repository.RepositoryItem, atg.repository.MutableRepositoryItem
IntegrationRepositoryView extends atg.repository.RepositoryViewImpl

In addition, each IntegrationRepositoryItemDescriptor refers to one or more commands, which implement the atg.integrations.Command interface. The RPC call in a Command returns an object of the atg.integrations.CommandResult class. Command and CommandResult are discussed in the Remote Procedure Calls chapter.


extends RepositoryImpl

The IntegrationRepository references another repository, which is referred to as the local repository and which is a SQL repository. The IntegrationRepository is defined by a Nucleus properties file and an XML definition file. Each method call functions as described in the following table, forwarding the request either to the local repository or to the IntegrationRepositoryItemDescriptor, which then executes a Command against the remote system.




The SQL repository that acts as a local repository. The local repository is a normal SQL repository. It might be configured in a properties file like this:




The Integration Repository definition file. This is an XML file that uses the Integration Repository DTD, . See Integration Repository Definition File for information about creating an Integration Repository definition file

This is a property of type atg.adapter.integrations.
. This class provides a set of helper methods that are used to convert between the local repository items and the remote system’s data format. An instance of this class exists at /atg/integrations/repository/IntegrationRepositoryTools.

This is a property of type atg.adapter.integrations.PersistentCacheManager. This class provides management of persistent caching. An instance of this class exists at /atg/integrations/repository/PersistentCacheManager. See the Persistent Caching section.

This is a property of type atg.repository.databinding.MappingManager. You can optionally define a mapping of the local repository item to the data on the remote system. This class manages that mapping. See Mapping in this chapter and see also the ATG Web Services Guide.

This is a property of type atg.repository.databinding.MappingTools, which is a helper class to manage the mappings. An instance of this class exists at /atg/integrations/repository/MappingTools.

The Integration Repository needs to deal with the case of a Command timing out before a result is returned from the remote system. If the Command times out, this property defines what the default behavior should be. There are four choices:

ROLLBACK - Rollback the current transaction.
INVALID - Mark the item’s state as invalid. See Persistent Caching.
UNKNOWN - Mark the item’s state as unknown. See Persistent Caching.
IGNORE - Do nothing.

A boolean property that controls whether the repository sends scenario events. The Integration Framework includes one scenario event by default, atg.adapter.integrations.IntegrationExternalIdChange, which is sent when the externalId of an item is set. To trigger this event, use the IntegrationRepositoryTools.externalIDWasUpdated method.


Most methods in the IntegrationRepository class are pass-through to the local repository. The following methods provide special behavior:

Depending on how you have configured the Integration Repository, this method either:

Calls localRepository.getItem and, if the result is null, then calls IntegrationRepositoryItemDescriptor.getRemoteItem, or

Calls IntegrationRepositoryItemDescriptor.getRemoteItem and, if the result is null, then calls localRepository.getItem, or

Calls IntegrationRepositoryItemDescriptor.getRemoteItem only.

Both the local repository’s query cache and the IntegrationRepository’s query cache will be used depending on the item descriptor. If the IntegrationRepository definition file includes a query Command, then the IntegrationRepository executes the query (and uses its query cache). If there is no query Command, then the query is forwarded to the local repository.

For a more detailed description, see getItem in the Command Operations section.

This method can operate in two ways. If querying is implemented in the local repository (no query command) then this returns a LocalRepositoryViewWrapper. If a Command is used for querying then this returns the configured RepositoryView class.

Return an IntegrationRepositoryItemDescriptor that wraps an item descriptor from the local repository. The local repository’s item cache will be used.

Return one (or more) IntegrationRepositoryItem, using similar behavior to the getItem method above.

Call localRepository.createItem. This method is just a pass through. See addItem.

Call localRepository.addItem. Also call IntegrationRepositoryItemDescriptor.addRemoteItem. For a more detailed description, see addItem in the Command Operations section.

Call localRepository.updateItem. Also call IntegrationRepositoryItemDescriptor.updateRemoteItem. For a more detailed description, see updateItem in the Command Operations section.

Call localRepository.removeItem. Also call IntegrationRepositoryItemDescriptor.removeRemoteItem. For a more detailed description, see removeItem in the Command Operations section.

Each of the Command executions is relevant only if the given command is defined for the item descriptor.


extends ItemDescriptorImpl

This class references an item descriptor from the local repository. Most operations will be pass-through to the local repository item descriptor. The following operations (described in the Command Operations section) execute a Command if one is defined for the item descriptor; otherwise they do nothing.


In addition, this class is responsible for converting the results of queries obtained from the remote system into repository items.


implements RepositoryItem, MutableRepositoryItem

This class references a repository item in the local repository. Most operations will be passed through to it.


implements RepositoryItem, MutableRepositoryItem

This class includes only the external ID property plus the list of properties in a RepositoryItem that have been changed. When, for example, updateItem is invoked on an IntegrationRepositoryItem, this wrapper can be passed to the update Command instead of the RepositoryItem. This allows us to send only the changed properties to be saved to the remote system, instead of trying to update all the properties of a repository item.

For example, if you change the middleName property of the user profile, and the user profile is configured with an external id property called remoteId, the ChangedPropertyBean will only expose two properties: middleName and remoteId. If you call ChangedPropertyBean.getPropertyDescriptors, the result will only contain these two properties. A ChangedPropertyBean is read-only.


implements RepositoryItem, MutableRepositoryItem

A MappingRepositoryItem wraps a repository item and exposes properties as they are configured in a mapping file. The Integration Repository creates MappingRepositoryItems automatically if it is configured with a mapping file. The property names that are exposed are the target names as defined in the mapping file. If a property’s include attribute is false in the mapping file, then that property is not a legal property of the MappingRepositoryItem. For example, if the following mapping exists:

 <property name="firstName" include="true"/>
 <property name="lastName" include="true"/>
 <property name="id" target-name="dynamoId" include="true"/>

then the corresponding MappingRepositoryItem would contain three properties: firstName, lastName, and dynamoId.


extends RepositoryViewImpl

IntegrationRepositoryView is an abstract class that provides some standard operations like applyOptions and getRange. For each type of remote system that you want to integrate with, you need to create an implementation of IntegrationRepositoryView specific for your remote system in order to provide the translation between the Oracle ATG Web Commerce Query format, and the format expected by the remote system. When a query is executed, the executeUncachedQuery method is called. That method looks like this:

public RepositoryItem[] executeUncachedQuery(Query pQuery, QueryOptions pOptions)
 // Step 1
 Object input = createQueryCommandInput(pQuery, pOptions);

 // Step 2
 RepositoryItem[] items = executeQueryCommand(input);

 // Step 3
 return applyOptions(items, pOptions);

The inputs to this method are a standard Query object and a standard QueryOptions object. The executeUncachedQuery method goes through the following steps:

Step 1
The first thing the view needs to do is translate the Query object into an object that is understandable by the remote system. This is the responsibility of your subclass of IntegrationRepositoryView and the only method that you must implement.

Step 2
This step is a call to the method defined in IntegrationRepositoryView that gets the correct Command according to your configuration and calls Command.execute with the provided query input.

Step 3
This step may not be necessary. If your remote system supports sorting and ranging (returning a subset of the items) then it will be more efficient for that information to be included in the command input. In that case this step can be skipped in the executeUncachedQuery and you should override the applyOptions method to do nothing.

The only thing required for querying to work is to subclass IntegrationRepositoryView and implement createQueryCommandInput. The implementation of this method will introspect the Query class and create an input object. The type and contents of the input object depend on the requirements of your application and the remote system you are querying. You then need to create a Command that knows what to do with this input.

In addition, you will typically need to implement a processResults method in your IntegrationRepositoryView subclass. This method is responsible for translating between the remote data format and the repository items in the local repository.

The default implementation of IntegrationRepositoryView.processResults calls IntegrationRepositoryTools.createRepositoryItems. It passes in the results from pCommandResult.getResults() as the first argument. The createRepositoryItems method uses DynamicBeans to look at the given command results. For each object in the result it uses the IntegrationRepositoryItemDescriptor to find the external ID. It uses this external ID to look for an existing item in the local repository with the same external ID. If one is found, this method iterates across the properties in the result object (using DynamicBeans) and updates the properties. If one is not found, a new item is first created, then the properties are updated.

Copyright © 1997, 2013 Oracle and/or its affiliates. All rights reserved. Legal Notices