edu.ucsb.adl.bucket99
Interface MetadataSubdriver

All Known Implementing Classes:

BlobMetadataSubdriver, DatabaseURLMetadataSubdriver, GenericQueryMetadataSubdriver, TemplateURLMetadataSubdriver

public interface MetadataSubdriver

The interface between the Bucket99 metadata driver and subdrivers that generate individual metadata views. The metadata driver creates the subdriver for a view by dynamically loading the subdriver class and calling the following class method:

public static MetadataSubdriver createSubdriver (
    ExtendedProperties propertyList, String prefix)

Subdriver startup parameters can be obtained from propertyList. prefix is the property name prefix corresponding to the metadata view, e.g., "ACCESS". If prefix is V, it is recommended that the names of view-specific startup parameters be prefixed with "V.".

The Bucket99 metadata driver maintains a single connection to a database, and it makes this connection available to all subdrivers by calling the subdrivers' useConnection method. When any subdriver throws an SQLException, the metadata driver 1) requests that all subdrivers remove their dependencies on the connection by calling the subdrivers' disuseConnection method; 2) closes the connection; 3) opens a new connection; and 4) makes the new connection available to all subdrivers.

Subdrivers need not be multithread-safe. The Bucket99 metadata driver guarantees that subdriver methods are called in the following order:

                              +------------------+
             +--------------> | disuseConnection |
             |                +------------------+
             |                         ^
             |                         |
             v                         |
     +---------------+         +----------------+
---> | useConnection | ------> | generateReport | ---+
     +---------------+         +----------------+    |
                                       ^             |
                                       |             |
                                       +-------------+

Not shown in the above diagram is the destroy method, which may be called at any time (and is of course the last subdriver method called).

Version:

$Header: /export/home/gjanee/bucket99/edu/ucsb/adl/bucket99/RCS/MetadataSubdriver.java,v 1.3 2004/09/23 16:24:14 gjanee Exp $

$Log: MetadataSubdriver.java,v $ Revision 1.3 2004/09/23 16:24:14 gjanee
Minor documentation change.

Revision 1.2 2003/06/10 20:31:06 gjanee
Added support for arbitrary, per-collection and per-holding metadata views. Specifically, the createSubdriver method is now passed a property name prefix.

Revision 1.1 2000/05/16 17:07:54 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Method Summary

void	destroy() Frees any resources held by the subdriver.
void	disuseConnection() Called by the Bucket99 metadata driver to request that the subdriver remove all dependencies on the current database connection.
java.lang.String	generateReport(java.lang.String view, java.lang.String collection, java.lang.String holding) Returns the view of the metadata for a holding within the collection.
void	useConnection(java.sql.Connection connection) Called by the Bucket99 metadata driver to supply a database connection for the subdriver's use.

Method Detail

useConnection

public void useConnection(java.sql.Connection connection)
                   throws java.sql.SQLException

Called by the Bucket99 metadata driver to supply a database connection for the subdriver's use.

Parameters:

connection - The connection.

Throws:

java.sql.SQLException - If any error occurs.

disuseConnection

public void disuseConnection()

Called by the Bucket99 metadata driver to request that the subdriver remove all dependencies on the current database connection.

generateReport

public java.lang.String generateReport(java.lang.String view,
                                       java.lang.String collection,
                                       java.lang.String holding)
                                throws java.sql.SQLException,
                                       MiddlewareException

Returns the view of the metadata for a holding within the collection. The subdriver can assume that the request has been authorized, that view names the view for which the subdriver was created, and that collection names the collection for which the metadata driver was created. This method need not be multithread-safe.

Parameters:

view - The metadata view, e.g., "adl:bucket".

collection - The collection name, e.g., "adl_catalog".

holding - The holding identifier.

Returns:

An XML document that is well-formed and valid according to the appropriate DTD.

Throws:

java.sql.SQLException - If a database-related error occurs that requires that the database connection be replaced.

BadRequestException - If holding is not a valid holding identifier.

InternalErrorException - If the request cannot otherwise be completed.

MiddlewareException

destroy

public void destroy()

Frees any resources held by the subdriver.