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:
Fetch a mutable version of the repository item through the
getItemForUpdate
andgetItemsForUpdate
methods. These methods return instances ofMutableRepositoryItem
. This interface extendsRepositoryItem
and adds one method:setPropertyValue(String pPropertyName, Object pPropertyValue)
Use the
setPropertyValue
method ofMutableRepositoryItem
to change as many properties as you wish. These changes will not be reflected in the repository until the finalupdateItem
operation is invoked.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 the update may happen automatically when the associated transaction commits. See Repositories and Transactions in the SQL Repository Architecture chapter. If there was any type of error, aRepositoryException
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 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:
atg.repository.servlet.RepositoryFormHandler
atg.userprofiling.ProfileForm
atg.userprofiling.ProfileFormHandler
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.