You use the updateItem()
method of the atg.repository.xml.UpdateService
class to modify a repository item. For example, the following instance document updates a user’s email address:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user
UserProfiles+user.xsd " ID="user747">
<user:user.emailAddress>sandy@example.com</user:user.emailAddress>
</user:user>
The updateItem()
method can optionally validate the instance document against the specified Schema. The logic for this is similar to the AddService.addItem()
method: the UpdateService
component has a validate
property whose default value is false
, and the updateItem()
method can take a Boolean argument that overrides the value of the validate
property.
Selecting the Item to Update
There are two ways to select the item to update:
You can specify the item explicitly when you call
updateItem()
.You can specify a set of match properties, and
updateItem()
selects the item whose values match the corresponding values in the instance document.
For example, the login
property is often used for matching, because it is unique to a specific user item and its value does not change. The following XML instance document could be used to select the item and then update its emailAddress
property:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user
UserProfiles+user.xsd " ID="user747">
<user:user.emailAddress>sandy@example.com</user:user.emailAddress>
<user:user.login>sandy</user:user.login>
</user:user>
The application would then use the following code to update the user repository item whose login
value is sandy (assuming the inputXML
String contains the instance document shown above):
String[] matchProperties = {"login"};
RepositoryItem updatedItem = UpdateService.updateItem(inputXML,
matchProperties);
Note that UpdateService determines the repository and item type from the namespace of the instance document. For more information, see Namespaces in the Getting Repository Items section.
The matchProperties
array can contain any number of property names. If the value of each repository item property named in matchProperties
matches its corresponding attribute in the XML instance document, the item is selected for update. All of the specified properties must match for the item to be selected; for example, if matchProperties
lists login
and lastName
properties, the values of both properties must match. If multiple items are selected, an exception is thrown and no update occurs.
Matching is limited to top-level properties of the repository item. Subproperties (such as properties of other repository items) cannot be matched. So, for example, if a user
item has a lastName
property that is a String
, you can include lastName
in matchProperties
; but if a
user
item has a shippingAddress
property that is another repository item, you cannot include, say, shippingAddress.city
in matchProperties
.
If a property has been mapped to a different name in the instance document, the name to match on is the property name used in the repository, not the instance document. For example, suppose you use a mapping file to map a user item’s dateOfBirth
property to the name birthday
, like this:
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="user" default-include="true">
<property name="dateOfBirth" targetName="birthday"/>
The corresponding instance document might look like this:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user
UserProfiles+user.xsd " ID="user747">
<user:user.birthday>02-06-1975</user:user.birthday>
</user:user>
To specify this property in matchProperties
, you use the name of the property as it is defined in the repository (dateOfBirth
), not the target name (birthday
). For example:
String[] matchProperties = {"dateOfBirth"};
You can configure the UpdateService
to add a repository item if an attempt to update does not find a match. If you want the UpdateService
to add items when no items are matched, set the addWhenNoMatchedItems
property of the UpdateService
to true
.
If the property being updated is a simple type (such as a String), then its value is updated by the UpdateService
. When the property being updated is a list, map or array, then the old value is replaced by the new value. The new value is not appended to the old value. If the property being updated is an item descriptor, then the appropriate fields of the existing item descriptors are updated.
repositoryId
The repositoryId
attribute of an item can be used as a special match property. If the repositoryId
String
is passed to UpdateService
as a match property, the service will determine the value of this attribute from the top-level XML element in the instance document, and then find a repository item with a matching repository ID. The following XML example uses the repositoryId
attribute as a match property:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user
UserProfiles+user.xsd " ID="user747" repositoryId="user707">
<user:user.emailAddress>sandy@example.com</user:user.emailAddress>
</user:user>
String[] matchProperties = {"repositoryId"};
RepositoryItem updatedItem = UpdateService.updateItem(inputXML,
matchProperties);
In this case, the UpdateService
selects the user item whose repositoryId
is "user707"
from /atg/userprofiling/ProfileAdapterRepository
.
Note: Do not confuse with the repositoryId
attribute, which identifies a repository item, with the ID
attribute used in the XML schema to identify an XML element. The repositoryId
attribute and not the ID
attribute is used to identify which repository item to update.