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 and thread-safe. 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 StandardModel 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(String title, 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(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.

Returns:

true if the database is writable, false if not.

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.)

Parameters:

id - SongID

Returns:

the Song, or null if the id doesn't exist in this database.

Throws:

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

NullPointerException - id was null

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.

Parameters:

id - SongID to test

Returns:

true if the given SongID exists in this database.

Throws:

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

NullPointerException - id was null

getSongIDForString

public SongID getSongIDForString(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.

Parameters:

idStr - serialized ID

Returns:

SongID

Throws:

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

createEmptyResultSet

public SongIDResultSet createEmptyResultSet()

Create an empty result set.

Returns:

empty SongIDResultSet

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.

Parameters:

operation - SongOperation to perform

param - input result set

Returns:

output result set

Throws:

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

addEmptySong

public SongID addEmptySong(String title,
                           Locale locale)
                    throws SongDatabaseFailedException

Add a new empty Song to the database.

Parameters:

title - main title of song to add

locale - Locale of song to add, or null to use the default locale

Returns:

ID of added Song

Throws:

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

NullPointerException - title was null

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.

Returns:

ID of added Song

Throws:

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

NullPointerException - original was null

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.

Parameters:

id - SongID of song to remove

Returns:

true if removed

Throws:

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

NullPointerException - id was null

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.

Parameters:

song - song to test

Returns:

true if the song is fresh.

Throws:

SongDeletedException - someone deleted this song in the meantime

SongDatabaseFailedException - Catch-all exception for database-related problems. This will often have a cause exception, which may be exceptions like IOException or SQLException.

IllegalArgumentException - this database is not the owner of the Song

NullPointerException - song was null

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.

Parameters:

song - song to commit

Throws:

SongNotFreshException - someone committed a change in the meantime

SongDeletedException - someone deleted this song in the meantime

SongDatabaseFailedException - Catch-all exception for database-related problems. This will always have a cause exception, which may be exceptions like IOException or SQLException.

IllegalArgumentException - this database is not the owner of the Song

NullPointerException - song was null

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.)

Parameters:

song - song to commit

Throws:

SongDeletedException - someone deleted this song in the meantime

SongDatabaseFailedException - Catch-all exception for database-related problems. This will always have a cause exception, which may be exceptions like IOException or SQLException.

IllegalArgumentException - this database is not the owner of the Song

NullPointerException - song was null

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.

Parameters:

song - song to commit

songID - SongID to commit as

Throws:

SongDeletedException - someone deleted the SongID

SongDatabaseFailedException - Catch-all exception for database-related problems. This will always have a cause exception, which may be exceptions like IOException or SQLException.

IllegalArgumentException - this database is not the owner of the SongID

NullPointerException - song or songID was null