The atg.repository.xml package includes a service class for each of the four repository operations supported by the data binding facility. The following table lists these classes and the Nucleus instances included in Dynamo:

The following sections discuss each of these classes and the operations they perform. See the entries for these classes in the ATG Platform API Reference for more information.

Getting Repository Items

You use getItemAsXML() method of the atg.repository.xml.GetService class to create XML documents from repository items. This method takes a repository item as an input argument and returns a String containing an XML representation of this item. If you write out this String (e.g., to a file), be sure to use the same character encoding that the repository uses.

Some versions of the getItemAsXML() method take additional inputs for specifying a String array of the names of the properties to write out or a String containing the name of the mapping file to use. If you supply only a repository item as input, the method uses the default inclusion rules (described in the Mapping Files section) to determine which properties to include.

By default, GetService writes out an XML document as a single line, because it is intended to be machine-readable. If you want the generated XML to be human-readable, set the indentXMLOutput property of the GetService component to true. The resulting XML will have appropriate line breaks.

The following example shows a repository operation to get a repository item.

Suppose you want to generate XML for a user profile, based on a mapping file named profileMapping.xml. The following code finds the user repository item whose ID is "user747" and generates an XML representation of it:

RepositoryItem userItem = getProfileRepository().getItem("user747",
 "user");
String userAsXML = GetService.getItemAsXML(userItem,"profileMapping.xml");

The following is sample output from this code. The data represents the profile of the user sandy in the Quincy Funds demo:

<user:user xmlns:user="http://www.atg.com/ns/profileMapping/UserProfiles/user"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user
 profileMapping+UserProfiles+user.xsd " ID="user747">
 <user:securityStatus>0</user:securityStatus>
 <user:actualGoals>long-term</user:actualGoals>
 <user:gender>female</user:gender>
 <user:fundShares>
 <user:integer>500</user:integer>
 <user:integer>220</user:integer>
 <user:integer>180</user:integer>
 <user:integer>260</user:integer>
 </user:fundShares>
 <user:goals>short-term</user:goals>
 <user:dateOfBirth>1976-12-09</user:dateOfBirth>
 <user:pubPrivileges>none</user:pubPrivileges>
 <user:homeAddress>
 <user:homeAddresscontactInfo ID="contactInfo747"/>
 </user:homeAddress>
 <user:numberNewsItems>4</user:numberNewsItems>
 <user:strategy>conservative</user:strategy>
 <user:locale>en_US</user:locale>
 <user:lastActivity>2002-08-14T18:33:49.604</user:lastActivity>
 <user:aggressiveIndex>5</user:aggressiveIndex>
 <user:lastName>Pieta</user:lastName>
 <user:actualStrategy>conservative</user:actualStrategy>
 <user:interests>
 <user:string>tax</user:string>
 <user:string>international</user:string>
 </user:interests>
 <user:id>747</user:id>
 <user:fundList>
 <user:string>/repositories/Funds/en_US/overseas.xml</user:string>
 <user:string>/repositories/Funds/en_US/moneymarket.xml</user:string>
 <user:string>/repositories/Funds/en_US/growth.xml</user:string>
 <user:string>/repositories/Funds/en_US/growthincome.xml</user:string>
 </user:fundList>
 <user:email>sandy@example.com</user:email>
 <user:password>d686a53fb86a6c31fa6faa1d9333267e</user:password>
 <user:registrationDate>1999-04-15T00:00:00.0</user:registrationDate>
 <user:userType>investor</user:userType>
 <user:member>true</user:member>
 <user:brokerId>734</user:brokerId>
 <user:numberFeatureItems>3</user:numberFeatureItems>
 <user:login>sandy</user:login>
 <user:guests>false</user:guests>
 <user:brokers>false</user:brokers>
 <user:investors>true</user:investors>
</user:user>

Notice that information about the XML Schema for this data is included in the user:user tag at the beginning of the document:

xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user
 profileMapping+UserProfiles+user.xsd "

The xsi:schemaLocation attribute specifies the URL and name of the Schema file. The Schema filename (profileMapping+UserProfiles+user.xsd) is determined by the name of the mapping file (profileMapping.xml), the name of the repository (UserProfiles), and the item descriptor (user). If no mapping file is used to create the document, the Schema filename indicates the repository and item descriptor. If you want the Schema filename to include the entire pathname, set the appendRelativeSchemaLocation property of the GetService component to true. This is especially important if you’re using an external Schema verification tool, which will generally need the complete pathname to find the Schema file.

If you use a mapping file when you create an instance document, you should be sure to supply the name of this mapping file to the generateXMLSchema command (using the –mappingFile argument) when you generate the Schema. Otherwise the actual Schema filename will not match the name in the xsi:schemaLocation tag, and the Schema may not accurately reflect the data in the instance document; as a result, you may not be able to validate the data when reading it into a remote system (or reading it back into Dynamo using AddService). Note also that if your call to getItemAsXML() includes an input argument that specifies the names of properties to write out, the Schema will not accurately reflect the data in the instance document, so validation will not be possible.

To avoid any conflict between tag names, the XML tags in the generated instance document are named using the convention itemType:propertyName; for example the user:userType tag stores the value of the userType property of the user item type. If the addItemTypeToPropertyNames property of the RepositoryXMLTools component that GetService points to is set to true, the tags are named using the convention itemType:itemType.propertyName; in this case, the tag name would be user:user.userType. By default addItemTypeToPropertyNames is set to true, because the resulting XML is less likely to result in naming collisions.

Adding Repository Items

You use the addItem() method of the atg.repository.xml.AddService class to create new repository items from XML documents. This method takes an XML document as an input argument and returns a repository item. The XML document can be in the form of a String, a java.io.Reader, or a java.io.InputStream. The method examines the schemaLocation attribute in the XML document to determine if there is a mapping file associated with the document. Some versions of the method take additional arguments for specifying how to handle missing or empty tags, and whether the data should be validated against a Schema.

For some examples of how a repository item might look in XML document form, see the <ATG10dir>/RL/Example/j2ee-apps/example/web-app/public directory. The Repository Loader (RL) module also includes a page you can use to generate XML documents from existing repository items. This page is located at <ATG10dir>/RL/Example/j2ee-apps/example/web-app/itemAsXml.jsp.

Note that addItem() cannot create new read-only elements in a repository. By default, any data in the instance document that corresponds to a read-only element in the repository is silently ignored. If you want addItem() to log a warning each time it skips a read-only element, set the logWarningOnReadOnly property of the AddService component to true.

Validating Repository Item Data

The addItem() method can optionally validate the data in an XML instance document against the Schema specified in the instance document. Validation is enabled or disabled by the validate property of the AddService component. By default, this property is set to false, because validation slows down processing of the document. To enable validation, set the validate property to true.

The addItem() method can also take a Boolean argument to specify whether to validate the document. The value of this argument overrides the validate property. If you do not specify this argument, addItem() uses the validate property to determine whether to validate the document.

If you are confident that your data is valid, you can disable validation, and the instance document will be processed more quickly. However, if the data turns out to be invalid, the invalid data may be written to the repository. If you enable validation and the data is invalid, addItem() does not write the contents of the instance document to the repository.

Updating Repository Items

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.

See Selecting Repository Items to Update and Using the repositoryId Attribute.

Selecting Repository Items to Update

There are two ways to select the item to update:

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. See Getting Repository Items.

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.

Using the repositoryId Attribute

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.

Removing Repository Items

You use the removeItems() method of the atg.repository.xml.RemoveService class to delete repository items specified in XML documents. This method takes an XML document in the form of a String array, a java.io.Reader, or a java.io.inputStream.

Some versions of removeItems() take a matchProperties String array. Property matching for RemoveService.removeItems() uses the same logic as UpdateService.updateItem(), except it is legal for multiple repository items to be marked for deletion. For example, an instance document to remove all users whose date of birth is 02-06-1975 would look like:

<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.dateOfBirth>02-06-1975</user:user.dateOfBirth>
</user:user>

The application then uses the following code to remove all the user repository items whose dateOfBirth value is 02-06-1975 (assuming the inputXML String contains the instance document shown above):

String[] matchProperties = {"dateOfBirth"};
String[] removedItemIds =
 RemoveService.removeItem(inputXML,matchProperties);

The maximum number of matching items is specified by the maxSelectedItems property of RemoveService. If the number of matching repository items exceeds this value, an exception is thrown. In the /atg/repository/xml/RemoveService component, maxSelectedItems is set to 5 by default.