|
|||||||||
| Home >> All >> com >> virtuosotechnologies >> asaph >> [ model overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
com.virtuosotechnologies.asaph.model
Interface SongDatabase
- public interface SongDatabase
This interface represents a database of songs. It provides facilities for simple searches by keyword and title, and allows clients to check out copies of songs, and check in changes.
This interface also specifies that all operations are atomic. That is, every mutation operation is atomic-- simultaneous mutations are serialized so they will not conflict. In addition, any query operation will always return information about a self-consistent state that the database was or could have been in at some point in the past. In-memory representations such as DOMImpl can implement this trivially by synchronizing each method, but an implementation with a SQL backend may require more work to implement these semantics.
Atomicity is not guaranteed for any of the other model interfaces.
| Method Summary | |
SongID |
addCopyOfSong(Song original)
Makes a copy of the given song and adds it to the database. |
SongID |
addEmptySong(java.lang.String title,
java.util.Locale locale)
Add a new empty Song to the database. |
Song |
checkOutSong(SongID id)
Get a song by SongID. |
void |
commitSong(Song song)
Commit changes to this song. |
boolean |
containsSongID(SongID id)
Tests whether the given song id exists in this database. |
SongIDResultSet |
createEmptyResultSet()
Create an empty result set. |
void |
forceCommitSong(Song song)
Commit changes to this song. |
void |
forceCommitSongAs(Song song,
SongID songID)
Force-commit a song as the given SongID. |
SongID |
getSongIDForString(java.lang.String idStr)
Get the SongID for the given string, if it exists. |
boolean |
isSongFresh(Song song)
Check the commit count to see if this song is still fresh. |
boolean |
isWritable()
Returns true if the database is writable. |
SongIDResultSet |
performOperation(SongOperation operation,
SongIDResultSet param)
Perform an operation on a set of songs. |
boolean |
removeSong(SongID id)
Remove the given song from the database. |
| Method Detail |
isWritable
public boolean isWritable()
- Returns true if the database is writable. If this returns false, every mutation
method will throw DatabaseNotWritableException. Note that even if this returns
false, the database may still be changed by other entities. In other words,
this method reflects the ability to write to the database through this interface,
not necessarily through all interfaces.
checkOutSong
public Song checkOutSong(SongID id) throws SongDatabaseFailedException
- Get a song by SongID. Note that the Song returned is a copy. Changes
do not get reflected in the database until commitSong() succeeds.
Returns null if the song doesn't exist in this database. (This could
mean the song was deleted, or it is part of a different database.)
containsSongID
public boolean containsSongID(SongID id) throws SongDatabaseFailedException
- Tests whether the given song id exists in this database. Returns
false if the song was deleted or if it is part of a different database.
getSongIDForString
public SongID getSongIDForString(java.lang.String idStr) throws SongDatabaseFailedException
- Get the SongID for the given string, if it exists. This is used to
deserialize a SongID that was stored persistently as its string
representation. Returns null if the string does not correspond to a
SongID that exists in this database.
createEmptyResultSet
public SongIDResultSet createEmptyResultSet()
- Create an empty result set.
performOperation
public SongIDResultSet performOperation(SongOperation operation, SongIDResultSet param) throws SongDatabaseFailedException
- Perform an operation on a set of songs. Operations could be accessors for
information that could be cached by the database, such as the main title, or they
could be filters applied to the result set, or they could have other semantics
such as mass-checkouts or mass-checkins.
The client specifies as the parameter a SongIDResultSet specifying the songs and
parameter data for the operation. If null is passed, the database creates a new
SongIDResultSet whose values are all the SongIDs in the database with null data
for each one.
The client also specifies the operation to perform.
The method performs the operation on the result set in place, and then returns it.
Note that some SongDatabase implementations may choose to optimize this method by not calling the operation directly, but by analzying the semantics of the operation as declared by which operation semantics interfaces are implemented, and performing accelerated operations such as checking caches. Thus, do not expect that the SongOperation object you pass will actually be invoked.
One common use of this method is to get a result set containing all the SongIDs in the database. This is accomplished by passing null for the parameter, and a NopSemantics implementation for the operation.
addEmptySong
public SongID addEmptySong(java.lang.String title, java.util.Locale locale) throws SongDatabaseFailedException
- Add a new empty Song to the database.
addCopyOfSong
public SongID addCopyOfSong(Song original) throws SongDatabaseFailedException
- Makes a copy of the given song and adds it to the database. The given song need
not be from this database.
On completion, the song in the database will be identical to the given song,
but the given song will not be modified. In particular, if the given song is
owned by a different database, it will still be owned by that database.
removeSong
public boolean removeSong(SongID id) throws SongDatabaseFailedException
- Remove the given song from the database. Returns true if the song existed
and was removed, or false if it was not present.
isSongFresh
public boolean isSongFresh(Song song) throws SongDeletedException, SongDatabaseFailedException
- Check the commit count to see if this song is still fresh. In other
words, this returns true if the song has not been committed by someone
else since this copy was checked out. Note that this should be taken to
mean "this song was fresh a little while ago." A return value of true
should not be taken as a guarantee that a subsequent call to commitSong
will not throw SongNotFreshException, because another client may commit
in between.
commitSong
public void commitSong(Song song) throws SongNotFreshException, SongDeletedException, SongDatabaseFailedException
- Commit changes to this song. Also sets this song to fresh, since it now
reflects the database contents. Does not perform the commit and throws
SongNotFreshException if someone already committed a change in the meantime.
forceCommitSong
public void forceCommitSong(Song song) throws SongDeletedException, SongDatabaseFailedException
- Commit changes to this song. Also sets this song to fresh, since it now
reflects the database contents. Commits and overwrites any changes made by
clients in the meantime. (In other words, doesn't throw SongNotFreshException.)
forceCommitSongAs
public void forceCommitSongAs(Song song, SongID songID) throws SongDeletedException, SongDatabaseFailedException
- Force-commit a song as the given SongID. The given SongID must be in this
database, but the given checked-out song need not be from this database.
On completion, the song in the database will be identical to the given song,
but the given song will not be modified. In particular, if the given song is
owned by a different database, it will still be owned by that database.
|
|||||||||
| Home >> All >> com >> virtuosotechnologies >> asaph >> [ model overview ] | PREV CLASS NEXT CLASS | ||||||||
|
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||