edu.ucsb.adl.middleware
Class ReferenceService

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

public final class ReferenceService

extends java.lang.Object

The ADL reference service. This service adds a permanent reference to a remote collection. Specifically, it creates a new local collection that uses an HTTP or RMI proxy driver to refer to a remote collection hosted by a remote middleware server.

This class reads the following properties from the main middleware configuration file. Property values may be indirectly specified using the notation @P where P is the name of another property (see ExtendedProperties for more information).

reference.gatekeeper.class

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

reference.gatekeeper.argument

The service-level gatekeeper's startup parameter.

reference.S.driver.gatekeeper.class

For service S, where S is "collection", "identifiers", "metadata", or "query": the fully-qualified name of the driver-level gatekeeper class to be used by service drivers for collections created by the reference service.

reference.S.driver.gatekeeper.argument

The startup parameter for the corresponding driver-level gatekeeper.

reference.query.polling_cycle_time

The duration of the RMI proxy driver's results polling loop in milliseconds, e.g., "1000" is 1 second. See QueryDriver.

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

Version:

$Header: /export/home/gjanee/middleware/edu/ucsb/adl/middleware/RCS/ReferenceService.java,v 1.7 2006/06/24 22:28:22 gjanee Exp $

$Log: ReferenceService.java,v $ Revision 1.7 2006/06/24 22:28:22 gjanee
Added support for the identifiers service. Simplified RMI URLs: the service prefix may now be omitted, in which case it is defaulted appropriately. Corrected a synchronization bug (but there is still the theoretical possibility of a conflict with the unreference service). Note that metadata report caching is currently disabled for proxy collections created by this service, not for any fundamental reason, but just because of the hassles of deciding where to cache reports and deleting report caches when remote collections are unreferenced.

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

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

Revision 1.4 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.3 2003/06/09 23:26:12 gjanee
Removed the full_report_dtd_url and access_report_dtd_url properties, as they are no longer needed.

Revision 1.2 2002/09/28 20:39:07 gjanee
Configuration file renames. Renamed the collection-specific middleware configuration file to drivers.conf and the RMI proxy driver configuration file to rmi-proxy-driver.conf.

Revision 1.1 2001/09/13 23:22:34 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Method Summary

static edu.ucsb.adl.middleware.ReferenceService	createService(java.lang.String configurationFile) Creates a ReferenceService.
void	destroy() Decrements the reference count.
void	performReferenceService(javax.servlet.ServletRequest request, java.lang.String baseUrl, java.lang.String remoteName, java.lang.String localName) Performs the ADL reference 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.ReferenceService createService(java.lang.String configurationFile)
                                                              throws InternalErrorException

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

performReferenceService

public void performReferenceService(javax.servlet.ServletRequest request,
                                    java.lang.String baseUrl,
                                    java.lang.String remoteName,
                                    java.lang.String localName)
                             throws MiddlewareException

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

Parameters:

request - The full request.

baseUrl - The remote middleware server's base URL, e.g., "rmi://host.com/prefix/" or "http://host.com/servlet/". In RMI URLs, the path portion of the URL (the "/prefix/" in the preceding example) may be omitted; if so, the service prefix is assumed to be "/edu/ucsb/adl/middleware/rmi/", which it is by default.

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

localName - The local name for the remote collection, or null if the remote name should be used.

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

destroy

public void destroy()

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