ATG Repository : MutableRepository

Some repository services implement MutableRepository, a subclass of Repository. The SQL repository
implements this interface. The MutableRepository interface defines these methods:

· createItem()
· addItem()
· removeItem()
· updateItem()


createItem() method 


There are two createItem methods:
createItem(String pDescriptorName) 
createItem(String pId, String pDescriptorName)


Each of these requires a DescriptorName parameter, which is the name of the RepositoryView or
ItemDescriptor that describes the repository item 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() method 
After you create an item, you can turn it into a persistent repository item with the addItem method. This
takes in the repository item that you want to add persistently:

RepositoryItem addItem(MutableRepositoryItem pItem)


removeItem() method 
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() method 
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:

1. Fetch a mutable version of the repository item through the getItemForUpdate and
getItemsForUpdate methods. These methods return instances of
MutableRepositoryItem. This interface extends RepositoryItem and adds one
method:
setPropertyValue(String pPropertyName, Object pPropertyValue) 


2. Use the setPropertyValue method of MutableRepositoryItem to change as
many properties as you wish. These changes are not reflected in the repository until
the final updateItem operation is invoked.

3. Save the changes with the updateItem method. This method extracts all the changes
required for the item and updates the item in the data store. Depending on how you
have configured transactional behavior, the update can be committed immediately, or
it can happen automatically when the associated transaction commits. See
Repositories and Transactions in the SQL Repository Architecture chapter. If there was
any type of error, a RepositoryException is thrown.

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:

· atg.repository.servlet.RepositoryFormHandler
· atg.userprofiling.ProfileForm
· atg.userprofiling.ProfileFormHandler

See the User 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 <ATG10dir>/DPS/src/Java/atg/userprofiling directory.