com.virtuosotechnologies.asaph.standardmodel
Interface StandardModelFactory


public interface StandardModelFactory

API for StandardModel.

This API is fully synchronized and thread-safe.


Field Summary
static StringID CURRENT_XML_FORMAT_CODE
          The format code given to new song databases created by this factory.
 
Method Summary
 SongDatabase createSimpleSongDatabase()
          Create a simple SongDatabase implementation.
 Song createSong(SongID id, Locale locale)
          Create a standard Song implementation.
 SongIDResultSet createSongIDResultSet(SongDatabase database)
          Create a standard SongIDResultSet implementation.
 StringID getDatabaseXMLFormatCode(SongDatabase database)
          Return the format code for the given simple SongDatabase.
 StringID getSongVersion(Song song)
          Get the version string for the given Song.
 StringID getSongXMLFormatCode(Song song)
          Return the format code for the given standard model Song.
 boolean isSimpleSongDatabase(SongDatabase database)
          Returns true if the given Song is a simple implementation of SongDatabase.
 boolean isStandardModelSong(Song song)
          Returns true if the given Song is a StandardModel implementation of Song.
 SongDatabase parseSimpleSongDatabase(Reader reader, ErrorHandler errorHandler, boolean writable)
          Parse a simple SongDatabase from the given XML document.
 Song parseSong(Reader reader, SongID id, ErrorHandler errorHandler)
          Parse a Song from the given XML document.
 void setSongVersion(Song song, StringID version)
          Set the version string for the given Song.
 void unparseSimpleSongDatabase(SongDatabase database, OutputStream stream, String encodingName)
          Unparse the given SongDatabase to an OutputStream as a standalone XML file.
 void unparseSimpleSongDatabase(SongDatabase database, Writer writer, String encodingName)
          Unparse the given SongDatabase to an OutputStream as a standalone XML file.
 void unparseSong(Song song, OutputStream stream, String encodingName)
          Unparse the given Song to an OutputStream as a standalone XML file.
 void unparseSong(Song song, Writer writer, String encodingName)
          Unparse the given Song to an OutputStream as a standalone XML file.
 void unparseSongElement(Song song, XMLUnparser unparser)
          Unparse the given Song to an OutputStream as an element within a larger XML document.
 

Field Detail

CURRENT_XML_FORMAT_CODE

public static final StringID CURRENT_XML_FORMAT_CODE
The format code given to new song databases created by this factory.

Method Detail

createSongIDResultSet

public SongIDResultSet createSongIDResultSet(SongDatabase database)
Create a standard SongIDResultSet implementation.

Parameters:
database - database that owns the result set
Returns:
an empty SongIDResultSet

createSong

public Song createSong(SongID id,
                       Locale locale)
Create a standard Song implementation.

Parameters:
id - SongID for the song, or null to create a standalone song
locale - Locale for the song, or null to use the default locale
Returns:
an empty Song

parseSong

public Song parseSong(Reader reader,
                      SongID id,
                      ErrorHandler errorHandler)
               throws IOException,
                      SAXException
Parse a Song from the given XML document.

Parameters:
reader - Reader to parse from
id - SongID for the song, or null to parse a standalone song
errorHandler - handler for error messages
Returns:
a new Song
Throws:
IOException - fatal i/o error
SAXException - fatal parse error

isStandardModelSong

public boolean isStandardModelSong(Song song)
Returns true if the given Song is a StandardModel implementation of Song. This means the song unparse operations provided by this API may be performed.

Parameters:
song - Song to test
Returns:
true if the Song is a StandardModel Song.

unparseSong

public void unparseSong(Song song,
                        OutputStream stream,
                        String encodingName)
                 throws IOException
Unparse the given Song to an OutputStream as a standalone XML file. The Song must be a StandardModel Song.

Parameters:
song - Song to unparse
stream - OutputStream to write to
encodingName - character encoding being used
Throws:
IOException - i/o error
IllegalArgumentException - the song isn't a StandardModel song

unparseSong

public void unparseSong(Song song,
                        Writer writer,
                        String encodingName)
                 throws IOException
Unparse the given Song to an OutputStream as a standalone XML file. The Song must be a StandardModel Song. Does not check to ensure the given writer's encoding matches the encoding string.

Parameters:
song - Song to unparse
writer - Writer to write to
encodingName - character encoding being used
Throws:
IOException - i/o error
IllegalArgumentException - the song isn't a StandardModel song

unparseSongElement

public void unparseSongElement(Song song,
                               XMLUnparser unparser)
                        throws IOException
Unparse the given Song to an OutputStream as an element within a larger XML document. The Song must be a StandardModel Song.

Parameters:
song - Song to unparse
unparser - XMLUnparser to use
Throws:
IOException - i/o error
IllegalArgumentException - the song isn't a StandardModel song

getSongXMLFormatCode

public StringID getSongXMLFormatCode(Song song)
Return the format code for the given standard model Song. This is an indication of the format of the xml last associated with this song. If this song is newly parsed from xml, this is the format given by that xml file. If this song was most recently unparsed to xml, this is the format written. If the song has never been associated with xml, this method will return null. The database must be a standardmodel Song.

Parameters:
song - Song to query
Returns:
the format code, or null
Throws:
IllegalArgumentException - the song isn't a standardmodel Song

getSongVersion

public StringID getSongVersion(Song song)
Get the version string for the given Song. The Song must be a StandardModel Song.

Parameters:
song - Song to query
Returns:
version string
Throws:
IllegalArgumentException - the song isn't a StandardModel song

setSongVersion

public void setSongVersion(Song song,
                           StringID version)
Set the version string for the given Song. The Song must be a StandardModel Song.

Parameters:
song - Song to query
version - version string
Throws:
IllegalArgumentException - the song isn't a StandardModel song

createSimpleSongDatabase

public SongDatabase createSimpleSongDatabase()
Create a simple SongDatabase implementation.

Returns:
an empty simple SongDatabase

parseSimpleSongDatabase

public SongDatabase parseSimpleSongDatabase(Reader reader,
                                            ErrorHandler errorHandler,
                                            boolean writable)
                                     throws IOException,
                                            SAXException
Parse a simple SongDatabase from the given XML document.

Parameters:
reader - Reader to parse from
errorHandler - handler for error messages
writable - should the database be writable
Returns:
a new simple SongDatabase
Throws:
IOException - fatal i/o error
SAXException - fatal parse error

isSimpleSongDatabase

public boolean isSimpleSongDatabase(SongDatabase database)
Returns true if the given Song is a simple implementation of SongDatabase. This means the song database unparse operations provided by this API may be performed.

Parameters:
database - SongDatabase to test
Returns:
true if the Song is a simple SongDatabase.

getDatabaseXMLFormatCode

public StringID getDatabaseXMLFormatCode(SongDatabase database)
Return the format code for the given simple SongDatabase. This is an indication of the format of the xml last associated with this database. If this database is newly parsed from xml, this is the format given by that xml file. If this database was most recently unparsed to xml, this is the format written. If the database has never been associated with xml (i.e. it has been newly created as an empty database), this method will return null. The database must be a simple SongDatabase.

Parameters:
database - SongDatabase to query
Returns:
the format code, or null
Throws:
IllegalArgumentException - the database isn't a simple SongDatabase

unparseSimpleSongDatabase

public void unparseSimpleSongDatabase(SongDatabase database,
                                      OutputStream stream,
                                      String encodingName)
                               throws IOException
Unparse the given SongDatabase to an OutputStream as a standalone XML file. The database must be a simple SongDatabase.

Parameters:
database - SongDatabase to unparse
stream - OutputStream to write to
encodingName - character encoding being used
Throws:
IOException - i/o error
IllegalArgumentException - the song isn't a simple SongDatabase

unparseSimpleSongDatabase

public void unparseSimpleSongDatabase(SongDatabase database,
                                      Writer writer,
                                      String encodingName)
                               throws IOException
Unparse the given SongDatabase to an OutputStream as a standalone XML file. The database must be a simple SongDatabase. Does not check to ensure the given writer's encoding matches the encoding string.

Parameters:
database - SongDatabase to unparse
writer - Writer to write to
encodingName - character encoding being used
Throws:
IOException - i/o error
IllegalArgumentException - the song isn't a simple SongDatabase