edu.ucsb.adl.middleware
Class MetadataService

java.lang.Object
  |
  +--edu.ucsb.adl.middleware.MetadataService

public final class MetadataService

extends java.lang.Object

The ADL metadata service. Conceptually, this service returns a view of the metadata for a holding within a collection. There are three standard ADL views:

adl:bucket

Describes the mappings of the holding's metadata to high-level search buckets.

adl:browse

Describes the browse-size representations of the holding that are available.

adl:access

Describes how to download or access the holding.

Other views, not defined by the middleware, may be supported by individual collections or even by individual holdings within collections. All metadata views are returned as complete, well-formed, valid XML documents. DTDs for the three standard ADL views are here.

The metadata service actually provides two methods. Method performMetadataService returns a specified metadata view for a holding within a collection as described above. Method performViewsService returns a list of the views supported by a holding within a collection.

This class reads the following properties from the main middleware configuration file:

metadata.validation

Must be either "on" or "off". If "on", all standard ADL metadata views returned by the metadata service are validated for correctness.

metadata.gatekeeper.class

The fully-qualified name of the service-level gatekeeper class, e.g., "edu.ucsb.adl.middleware.IPAddressGatekeeper".

metadata.gatekeeper.argument

The service-level gatekeeper's startup parameter.

collection_directory

The pathname of the directory in which collection-specific configuration files are stored, e.g., "/export/middleware/config/collections". If the pathname is not absolute, it is interpreted relative to the directory containing the main middleware configuration file.

If the value of the collection_directory property is D, then in loading collection C this class reads the following properties from the collection-specific middleware configuration file D/C/drivers.conf:

metadata.driver.class

For collection C, the fully-qualified name of the driver class, e.g., "edu.ucsb.adl.bucket99.MetadataDriver".

metadata.cache

Must be either "on" or "off". If "on", selective report caching is enabled; see CachingMetadataDriver.

metadata.driver.gatekeeper.class

For collection C, the fully-qualified name of the driver-level gatekeeper class.

metadata.driver.gatekeeper.argument

For collection C, the driver-level gatekeeper's startup parameter.

In all of the above configuration files, property values may be indirectly specified using the notation @P where P is the name of another property (see ExtendedProperties for more information). The main middleware configuration file serves as a properties default for the collection-specific configuration files.

Version:

$Header: /export/home/gjanee/middleware/edu/ucsb/adl/middleware/RCS/MetadataService.java,v 1.7 2006/06/22 23:33:10 gjanee Exp $

$Log: MetadataService.java,v $ Revision 1.7 2006/06/22 23:33:10 gjanee
Added support for metadata caching. If caching is enabled for a collection (as determined by the collection's metadata.cache property), then we wrap the collection's metadata driver with an instance of CachingMetadataDriver. Also, if a returned metadata report starts with the string "VALID", it is assumed to have come from the cache, and since only valid and processed reports are cached, all further validation and processing of the report is sidestepped.

Revision 1.6 2004/09/21 23:53:43 gjanee
Minor documentation change.

Revision 1.5 2004/03/05 18:52:05 gjanee
Added support for multiple middleware instances. A middleware instance is represented by a Global object that is tied to a main middleware configuration file. All service objects now maintain a reference to the appropriate Global object. Instance-wide variables formerly coded as class variables are now held by the Global object; various methods that return instance-wide variables now accept a Global object as an argument. The Global object is now passed to all service drivers.

Revision 1.4 2003/05/12 17:04:25 gjanee
Added support for arbitrary, per-collection and per-holding metadata views. Specifically, changed the view argument data type from an enumeration to a string. Added method performViewsService. Added validation of returned metadata. Added the metadata.validation property. Also, character encoding declarations in returned metadata are now removed (on the theory that they're either redundant or erroneous).

Revision 1.3 2002/09/28 20:29:23 gjanee
Configuration file renames. Renamed the collection-specific configuration file to drivers.conf.

Revision 1.2 2001/08/13 23:56:35 gjanee
Switched to the new configuration file structure. In the new structure, an entirely collection-independent "main" configuration file refers to a directory of subdirectories, one subdirectory per collection; each subdirectory holds a collection-specific middleware configuration file in addition to any configuration files required by the collection driver. Also, added support for dynamic collection loading/unloading. Collection drivers are now loaded on demand. The unloadCollection method unloads a driver.

Revision 1.1 1999/12/04 00:22:00 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Method Summary

static edu.ucsb.adl.middleware.MetadataService	createService(java.lang.String configurationFile) Creates a MetadataService.
void	destroy() Decrements the reference count.
java.lang.String	performMetadataService(javax.servlet.ServletRequest request, java.lang.String view, java.lang.String object) Performs the ADL metadata service.
java.lang.String[]	performViewsService(javax.servlet.ServletRequest request, java.lang.String object) Returns the views supported by a holding within a collection.
void	unloadCollection(java.lang.String collection) Unloads a collection (i.e., the driver and gatekeeper for a collection) from the service.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createService

public static edu.ucsb.adl.middleware.MetadataService createService(java.lang.String configurationFile)
                                                             throws InternalErrorException

Creates a MetadataService. If a service already exists for the configuration file, the extant service's reference count is incremented and it is returned instead.

Parameters:

configurationFile - The filename of a main middleware configuration file.

Throws:

InternalErrorException - If the initialization of the service fails.

performMetadataService

public java.lang.String performMetadataService(javax.servlet.ServletRequest request,
                                               java.lang.String view,
                                               java.lang.String object)
                                        throws MiddlewareException

Performs the ADL metadata service. This method is multithread-safe.

Parameters:

request - The full request.

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

object - An object identifier, which should have the form "C:H" where C is the name of a collection (e.g., "adl_catalog") and H is a collection-specific holding identifier.

Returns:

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

Throws:

BadRequestException - If any of the arguments is invalid.

NoAuthorizationException - If the request is valid but not allowed.

UnsupportedException - If the request is valid but not supported.

InternalErrorException - If the request cannot otherwise be completed.

MiddlewareException

performViewsService

public java.lang.String[] performViewsService(javax.servlet.ServletRequest request,
                                              java.lang.String object)
                                       throws MiddlewareException

Returns the views supported by a holding within a collection. This method is multithread-safe.

Parameters:

request - The full request.

object - An object identifier, which should have the form "C:H" where C is the name of a collection (e.g., "adl_catalog") and H is a collection-specific holding identifier.

Returns:

The views supported by the holding. The list includes the three standard ADL views.

Throws:

BadRequestException - If any of the arguments is invalid.

NoAuthorizationException - If the request is valid but not allowed.

InternalErrorException - If the request cannot otherwise be completed.

MiddlewareException

unloadCollection

public void unloadCollection(java.lang.String collection)

Unloads a collection (i.e., the driver and gatekeeper for a collection) from the service. If the collection has not yet been loaded or has already been unloaded, this method does nothing.

Parameters:

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

destroy

public void destroy()

Decrements the reference count. When the reference count drops to zero, all resources held by the service are freed.