edu.ucsb.adl.middleware
Class QueryService

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

public final class QueryService

extends java.lang.Object

The ADL query service. Conceptually, this service submits a query to one or more collections and immediately returns an integer that identifies both the running query and the result set that holds the results of the query.

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

query.lifetime

The lifetime of queries in milliseconds.

query.maximum_results

The maximum number of results a query may accumulate.

query.validation

Must be either "on" or "off". If "on", the standard ADL metadata views in query results are validated for correctness.

query.result_set_sharing

Must be either "on" or "off". If "on", textually identical queries share result sets.

result_set.lifetime

The lifetime of result sets in milliseconds.

result_set.reaper_cycle_time

The duration of the result set reaper's cycle in milliseconds.

result.initial_compression

Must be either "on" or "off". If "on", query results are compressed when added to a result set.

result.compression_age

The age in milliseconds at which query results are compressed, or the string "never" to disable compression (other than possibly an initial compression as determined by the result.initial_compression property). A query result's age is reset to zero each time one of its metadata views is accessed; accessing a metadata view, if compressed, causes the view to be uncompressed.

query.gatekeeper.class

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

query.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.

In the above, property values that are time durations in milliseconds may have a single-character suffix added to specify a different unit of measure. Recognized suffixes are "s" (seconds), "m" (minutes), "h" (hours), and "d" (days).

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:

query.driver.class

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

query.driver.gatekeeper.class

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

query.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/QueryService.java,v 1.9 2007/02/14 17:02:43 gjanee Exp $

$Log: QueryService.java,v $ Revision 1.9 2007/02/14 17:02:43 gjanee
Added support for result set sharing. Added the query.result_set_sharing property. Note that result set sharing introduces a number of considerations: logging (identical queries may not be logged); debugging (collection configuration changes may not be immediately apparent); client expectations regarding "ownership" of result sets (a client deleting its "own" result set may effectively delete another client's); and access control (by reusing another client's result set, a client may gain access to collections it would otherwise have no rights to).

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

Revision 1.7 2004/03/15 17:17:52 gjanee
Added support for compression of results. Added properties result.initial_compression and result.compression_age.

Revision 1.6 2004/03/11 19:21:24 gjanee
Added support for different units of measure in time duration properties.

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/06/09 20:06:02 gjanee
Added validation of query results. Added the query.validation property.

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

Revision 1.2 2001/08/17 20:47:45 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 2000/02/29 00:55:23 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Method Summary

static edu.ucsb.adl.middleware.QueryService	createService(java.lang.String configurationFile) Creates a QueryService.
void	destroy() Decrements the reference count.
int	performQueryService(javax.servlet.ServletRequest request, java.lang.String queryString) Performs the ADL query service.
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.QueryService createService(java.lang.String configurationFile)
                                                          throws InternalErrorException

Creates a QueryService. 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.

performQueryService

public int performQueryService(javax.servlet.ServletRequest request,
                               java.lang.String queryString)
                        throws MiddlewareException

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

Parameters:

request - The full request.

queryString - The query, expressed in XML according to the ADL-query DTD.

Returns:

An integer that identifies both the running query and the associated result set.

Throws:

BadRequestException - If either 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

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.