com.virtuosotechnologies.asaph.maingui
Interface DatabaseManager


public interface DatabaseManager

The song database manager API exported by the maingui plugin.

This API has some thread-safe methods and some methods that must be called from the AWT/Swing thread. See the individual method documentation for specifics.


Field Summary
static ClassConstrainedKey DATABASE_DIRTY_KEY
          Database property for the dirty bit.
static ClassConstrainedKey DATABASE_ICON_KEY
          Database property for the database icon.
static ClassConstrainedKey DATABASE_IDENTIFIER_KEY
          Database property for the database identifier.
static ClassConstrainedKey DATABASE_NAME_KEY
          Database property for the database name.
 
Method Summary
 void addDatabaseListener(DatabaseListener listener)
          Add a DatabaseListener to the main gui.
 DatabaseIdentifier createDatabaseIdentifier(String connectorName, String locator)
          Create a new DatabaseIdentifier from a connector name and a locator string.
 URI databaseIdentifierToURI(DatabaseIdentifier di)
          Create an URI for a DatabaseIdentifier.
 PropertySet getDatabaseProperties(SongDatabase database)
          Get a PropertySet providing a view of the properties of the given database.
 ObjectSet getOpenDatabaseSet()
          Get an ObjectSet view of the open databases.
 DatabaseController openDatabase(SongDatabase database, PropertySet properties, DatabaseHandler handler)
          Add a database to the list of open databases.
 SongDatabase openIdentifiedDatabase(DatabaseIdentifier identifier)
          Attempt to open the SongDatabase referenced by the given identifier.
 void registerDatabaseConnector(String name, StringID version, DatabaseConnector connector)
          Register a database connector.
 void removeDatabaseListener(DatabaseListener listener)
          Remove a DatabaseListener from the main gui.
 boolean setDatabaseDirtyBit(SongDatabase database)
          Set the dirty bit for a SongDatabase.
 DatabaseConnector unregisterDatabaseConnector(String name, StringID version)
          Unregister a database connector.
 DatabaseIdentifier uriToDatabaseIdentifier(URI uri)
          Create a new DatabaseIdentifier from an URI.
 

Field Detail

DATABASE_DIRTY_KEY

public static final ClassConstrainedKey DATABASE_DIRTY_KEY
Database property for the dirty bit. Class is Boolean.


DATABASE_NAME_KEY

public static final ClassConstrainedKey DATABASE_NAME_KEY
Database property for the database name. Class is String.


DATABASE_ICON_KEY

public static final ClassConstrainedKey DATABASE_ICON_KEY
Database property for the database icon. Class is Icon.


DATABASE_IDENTIFIER_KEY

public static final ClassConstrainedKey DATABASE_IDENTIFIER_KEY
Database property for the database identifier. Class is DatabaseIdentifier.

Method Detail

registerDatabaseConnector

public void registerDatabaseConnector(String name,
                                      StringID version,
                                      DatabaseConnector connector)
                               throws DuplicateConnectorException
Register a database connector. A plugin that connects to databases should call this method to provide a way to open database identified by DatabaseIdentifier. If a connector of the same name is already registered, the one with the higher version number overrides the lower version number.

This method is fully synchronized and thread-safe.

Parameters:
name - unique name for the connector. This name serves as a serializable reference to the connector. Characters allowed include alphanumeric characters, ".", "_" and "$".
version - a version number.
connector - the DatabaseConnector to register
Throws:
DuplicateConnectorNameException - tried to register a duplicate connector with the same name and version.
DuplicateConnectorException

unregisterDatabaseConnector

public DatabaseConnector unregisterDatabaseConnector(String name,
                                                     StringID version)
Unregister a database connector.

This method is fully synchronized and thread-safe.

Parameters:
name - unique name for the connector.
version - a version number.
Returns:
the unregistered connector, or null if it was not found

openDatabase

public DatabaseController openDatabase(SongDatabase database,
                                       PropertySet properties,
                                       DatabaseHandler handler)
Add a database to the list of open databases.

This method is not thread-safe, and should only be called from the AWT/Swing thread.

Parameters:
database - the database to open
properties - initial properties for the database
handler - a DatabaseHandler for the database
Returns:
an controller for the database

getOpenDatabaseSet

public ObjectSet getOpenDatabaseSet()
Get an ObjectSet view of the open databases. This set tracks databases as they are opened and closed.

This method is not thread-safe, and should only be called from the AWT/Swing thread. The returned ObjectSet is similarly not thread-safe and should only be accessed from the AWT/Swing thread.

Returns:
an ObjectSet of SongDatabase

getDatabaseProperties

public PropertySet getDatabaseProperties(SongDatabase database)
Get a PropertySet providing a view of the properties of the given database. This PropertySet tracks changes to the properties.

This method is not thread-safe, and should only be called from the AWT/Swing thread. The returned PropertySet is similarly not thread-safe and should only be accessed from the AWT/Swing thread.

Parameters:
database - SongDatabase to query
Returns:
a PropertySet.
Throws:
IllegalArgumentException - the given database is not open

setDatabaseDirtyBit

public boolean setDatabaseDirtyBit(SongDatabase database)
Set the dirty bit for a SongDatabase. A plugin should call this after making any modification to a database. The DatabaseHandler that opened the database is notified when this is called, and it decides whether it makes sense to set the dirty bit. If the dirty bit is set, either because of this call or because it was set before, true is returned; otherwise, false is returned.

This method is not thread-safe, and should only be called from the AWT/Swing thread.

Parameters:
database - SongDatabase to mark dirty
Returns:
true if the dirty bit is set after this call completes.
Throws:
IllegalArgumentException - the given database is not open

createDatabaseIdentifier

public DatabaseIdentifier createDatabaseIdentifier(String connectorName,
                                                   String locator)
Create a new DatabaseIdentifier from a connector name and a locator string.

This method is fully synchronized and thread-safe.

Parameters:
connectorName - Connector name. Characters allowed include alphanumeric characters, ".", "_" and "$".
locator - Locator string.
Returns:
a DatabaseIdentifier

uriToDatabaseIdentifier

public DatabaseIdentifier uriToDatabaseIdentifier(URI uri)
                                           throws URISyntaxException
Create a new DatabaseIdentifier from an URI.

This method is fully synchronized and thread-safe.

Parameters:
uri - the URI to parse.
Returns:
a DatabaseIdentifier
Throws:
URISyntaxException - unable to parse the URI

databaseIdentifierToURI

public URI databaseIdentifierToURI(DatabaseIdentifier di)
                            throws URISyntaxException
Create an URI for a DatabaseIdentifier.

This method is fully synchronized and thread-safe.

Parameters:
di - the DatabaseIdentifier.
Returns:
a DatabaseIdentifier
Throws:
URISyntaxException - unable to build URI

openIdentifiedDatabase

public SongDatabase openIdentifiedDatabase(DatabaseIdentifier identifier)
                                    throws SongDatabaseFailedException,
                                           UnrecognizedDatabaseIdentifierException
Attempt to open the SongDatabase referenced by the given identifier. Returns the SongDatabase opened. If no connector agrees to open the database, UnrecognizedDatabaseIdentifierException is thrown. If a connector agrees to open the database but fails, it will throw SongDatabaseFailedException.

This method is fully synchronized and thread-safe. Note that because it may be time-consuming, this method should normally be called off the gui thread (e.g. in an AsyncJob).

Parameters:
identifier - identifier for the database to open
Throws:
SongDatabaseFailedException - an error occurred while opening the database. This will usually have a cause exception, such as IOException or SQLException.
UnrecognizedDatabaseIdentifierException - no connector agreed to open the database

addDatabaseListener

public void addDatabaseListener(DatabaseListener listener)
Add a DatabaseListener to the main gui. Note that it is added as a weak listener, so make sure it is strongly referenced elsewhere.

This method is fully synchronized and thread-safe.

Parameters:
listener - DatabaseListener

removeDatabaseListener

public void removeDatabaseListener(DatabaseListener listener)
Remove a DatabaseListener from the main gui. Does nothing if the listener is not added.

This method is fully synchronized and thread-safe.

Parameters:
listener - DatabaseListener