Developing ATG Applications

Part I
Chapter 12 • The Repository API

Using ATG Repositories, Scenario PersonalizationSM

and the Dynamo Application Framework
Objectives
After completing this chapter, you will know how
to
• Use the ATG Repository API to manipulate

repository items within Java code, including

retrieving, creating, updating, deleting and
querying for items

12-2
Dynamusic Repository Access
• In examples so far, all Dynamusic repository
access has used standard servlet beans and form
handlers
• "Manager" components provide specialized
access to repositories that isn't supported by the
standard components

12-3
Example: SongsManager

SongsManager

repository
userRepository

addArtistToSong()

createArtistFromUser()
UploadSong
Handler firstArtistByName()

12-4
Repository API Overview
• The ATG Repository API is a set of interfaces used for
generic data access

Interface Key Methods

Repository getItem(), getView()
RepositoryItem getPropertyValue()
RepositoryView executeQuery()
MutableRepository addItem()
getItemForUpdate()
updateItem()
removeItem()
MutableRepositoryItem setPropertyValue()

12-5
Retrieving a Repository Item by ID
SongsManager.java
public void addArtistToSong(String pSongid, String
pArtistid) throws RepositoryException {
Repository repository = getRepository();
try {
RepositoryItem artistItem =
repository.getItem(pArtistid,"artist");
if (ifLoggingDebug())
logDebug("adding artist: " +
artistItem.getPropertyValue("name"));
}
catch (RepositoryException e) {
if (isLoggingError()) {
logError("Unable to add artist to song",
e);
}
throw e;
}
}…

12-6
Mutable Repositories (1)
• Repository and RepositoryItem provide a
read-only view of repository elements
• MutableRepository is an extension that
allows repository elements to be:
— Created

— Updated

— Deleted

• Manipulating a MutableRepositoryItem (a
local copy of the data) only changes the
repository when an explicit call to
updateItem()or addItem()is made

12-7
Mutable Repositories (2)
• Allow an item to be “checked out” of the
repository, modified, and then resubmitted (so
that the change will be reflected in the
underlying data store)
• Provide a locking mechanism which prohibits
any access of the data store while it is being
modified

12-8
Updating an Existing Item
• Get the item using getItemForUpdate()
• Change values by calling the item's
setPropertyValue() method
• Save changes to the repository using
updateItem()

12-9
 Example: Using Mutable Repositories
SongsManager.java

public void addArtistToSong(String pSongid, String

pArtistid) throws RepositoryException {
MutableRepository mutRepos = (MutableRepository)
getRepository();
try {
RepositoryItem artistItem =
repository.getItem(pArtistid,"artist");
1 MutableRepositoryItem mutSongItem =
mutRepos.getItemForUpdate(pSongid,"song");
2 mutSongItem.setPropertyValue("artist",artistItem);
3 mutRepos.updateItem(mutSongItem);
}
…

12-10
 Creating a New Item
1. Create a MutableRepositoryItem using
MutableRepository.createItem()
method

2. Set the item's properties using the

item’s setPropertyValue(String
pPropertyName, pPropertyValue)
method

3. Store the item in the repository using

MutableRepository.addItem() method

12-11
 Example: Creating a New Item
SongsManager.java
public String createArtistFromUser(String pUserid) throws
RepositoryException {
MutableRepository mutRepos = (MutableRepository)
getRepository();
RepositoryItem user =
getUserRepository().getItem(pUserid, "user");
String username =
(String)user.getPropertyValue("firstName") + " " +
user.getPropertyValue("lastName");
1 MutableRepositoryItem mutArtistItem =
mutRepos.createItem("artist");
2 mutArtistItem.setPropertyValue("name", username);
…copy all relevant properties…
3 mutRepos.addItem(mutArtistItem);
return mutArtistItem.getRepositoryId();
}

12-12
 Querying the Repository
• The most straightforward way of executing
queries in a repository is using RQL using the
RqlStatement class
• You can create an RQLStatement from a string
using parseRQLStatement()
RqlStatement statement =
RqlStatement.parseRqlStatement(
rql string);
• RQL statements are executed against a
RepositoryView

12-13
 Parameterized RQL
• The syntax for passing parameters to an RQL query is
different for the API than RQLQueryForEach
— ?n (where "n" is the parameter number)

• Parameters are passed in an array of Objects

— "n" is the index in the array

• Example: "Have any artists with this name been created

already?"
public String createArtistFromUser(String pUserid) … {
…
String username =
(String)user.getPropertyValue("firstName") + " " +
user.getPropertyValue("lastName");
RepositoryItem artistItem = findArtistByName(username);
if (artistItem==null) {
…
12-14
 Example: Executing RQL Queries
SongsManager.java
public RepositoryItem findArtistByName(String pArtistName)
throws RepositoryException {
Repository repos = getRepository();
RqlStatement findArtistRQL;
1 RepositoryView artistView = repos.getView("artist");
Object rqlparams[] = new Object[1];
2
rqlparams[0] = pArtistName;
findArtistRQL =
3
RqlStatement.parseRqlStatement("name = ?0");
RepositoryItem [] artistList =
findArtistRQL.executeQuery (artistView,rqlparams);

if (artistList != null) {
return artistList[0];
}
return null;
}
12-15
 Named Queries (1)
• You can also define a query in the SQL
repository definition file
songs.xml Example: a named
… query to return all
<item-descriptor name="song"> jazz songs in the
… repository
<named-query>
<rql-query>
<query-name>jazzSongs</query-name>
<rql>genre = "jazz"</rql>
</rql-query>
</named-query>

</item-descriptor>
…

12-16
 Named Queries (2)
• Two ways to execute a named query
- programmatically (use - in JSP (use the
the NamedQueryView NamedQueryForEach
object) droplet)

SongsManager

jazzSongs

12-17
 Named Queries: Programmatic Execution

SongsManager.java SongsManager
public RepositoryItem[] getJazzSongs() { jazzSongs
try {
RepositoryView songView =
getRepository().getView("song");
if(songView instanceof NamedQueryView) {
1 NamedQueryView nameView =
(NamedQueryView)songView;
Query namedQuery =
2 nameView.getNamedQuery("jazzSongs");
RepositoryItem[] results =
nameView.executeQuery(namedQuery);
}
return results;
}
…

12-18
 Named Queries: JSP
jazzsongs.jsp
<dsp:droplet
name="/atg/dynamo/droplet/NamedQueryForEach">
<dsp:param name="repository"
bean="/dynamusic/SongsRepository" />
<dsp:param name="queryName" value="jazzSongs" />
<dsp:param name="itemDescriptor" value="song" />
…
<dsp:oparam name="output">
<li>
<dsp:a href="song.jsp">
<dsp:param name="itemId" param="element.id"/>
<dsp:valueof param="element.title"/>
</dsp:a>
</dsp:oparam>
…
</dsp:droplet>
12-19
 Summary
In this chapter, you learned how to
• Use the Repository API to retrieve, create,

modify, delete and query for items in a

Repository
• Define and used a named query

12-20
 For More Information
• Repository Guide
— "Repository API"

— "Repository Queries"

• API Reference
— atg.repository package

12-21
 Exercises
• Implement the deleteAlbumsByArtist
method using Repository API calls
• Testing using a provided JSP, passing in the ID
of an Artist

12-22