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 may 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 will be 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 may attempt to re-fetch the object (if the user’s session has not expired or the server has not been restarted) 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 attempt to create anonymous user database records for web sites that have a large volume of users.

addItem

Once 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 will be deleted and will no longer be accessible from the repository:

removeItem(String pId, String pDescriptorName)

updateItem

The MutableRepository updates a repository item in a transactionally aware manner. It does not occur like standard JavaBeans because we want to make sure the update operation in the backend data store (such as a relational database) is efficient. Thus, updating an item takes 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 will be performed, but the values will be 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 <ATG2007.3dir>/DPS/src/Java/atg/userprofiling directory.