ATG Repository Guide

Some repository services implement MutableRepository, a subclass of Repository. The SQL repository implements this interface. The MutableRepository interface defines functions for four operations: creating, adding, updating, and removing repository items:

createItem()

There are two createItem methods:

createItem(String pDescriptorName)
createItem(String pId, String pDescriptorName)

Each of these requires a DescriptorName parameter, which should be the name of the RepositoryView or ItemDescriptor that describes the repository item you wish to create. Each repository has a default ItemDescriptor, which might allow your code to use the defaultViewName property of the repository to supply this value. One of the createItem methods takes a potential unique ID to use for the MutableRepositoryItem to create. If you do not supply an ID, one is automatically generated and guaranteed to be unique.

In the SQL profile repository, for example, the createItem methods return a transient instance of a MutableRepositoryItem. At this point, the profile does not exist persistently in a data store. The item exists only as the object reference you are returned. You can try to refetch the object (if the user’s session is not expired or the server did not restart) through the getItem(String pId, String pDescriptorName) method of the Repository (unless the GSARepository.storeTransientItems property is set to false). Maintaining profile RepositoryItems in RAM rather than in the profile database allows anonymous users to be represented in the same Repository API, but does not hamper performance for handling requests for large sites. It becomes untenable to try to create anonymous user database records for web sites that have a large volume of users.

addItem()

After an item is created, at some later point you might want to turn it into a persistent repository item. To do so, use the addItem method. This takes in the repository item that you want to add persistently:

RepositoryItem addItem(MutableRepositoryItem pItem)

removeItem()

Removing an item from the repository is very easy. Pass the ID and ItemDescriptor name of the item you want to remove persistently to the removeItem method. The item’s property values are deleted and are no longer accessible from the repository:

removeItem(String pId, String pDescriptorName)

updateItem()

The MutableRepository updates a repository item in a transactionally aware manner. It differs from a standard JavaBean in order to ensure that the update operation in the backend data store (such as a relational database) is efficient. Thus, updating an item requires three steps:

For example:

try {
   RepositoryItem user = ... // get a reference to the user you want to update
   MutableRepository mutableRepository = (MutableRepository)user.getRepository();
   MutableRepositoryItem mutableUser =
       mutableRepository.getItemForUpdate(user.getRepositoryId(),
                         user.getItemDescriptor().getItemDescriptorName());
   mutableUser.setPropertyValue("name", "bob");
   mutableUser.setPropertyValue("age", new Integer(26));
   mutableRepository.updateItem(mutableUser);
}
catch (RepositoryException exc) {
 // deal with exception
}

This same methodology should be applied for RAM-based RepositoryItems that you have created through the createItem method. No database transaction is performed, but the values are updated in the repository.

The Dynamo Application Framework (DAF) includes three classes that provide useful methods for dealing with repository items:

See the Using Profiles and Profile Forms chapter in the ATG Page Developer’s Guide and the source code for the ProfileForm and ProfileFormHandler classes, included in the ATG Personalization module distribution in the <ATG9dir>/DPS/src/Java/atg/userprofiling directory.