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