edu.ucsb.adl.middleware
Class ResultSet

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

public final class ResultSet

extends java.lang.Object

A result set, i.e., the results of a query. A result set stores:

• an integer ID;
• the associated query;
• the (partial or complete) results of the query in the form of zero or more triplets of reports (each triplet consists of an access report, a browse report, and a bucket report);
• a boolean flag indicating if the result set is complete;

and, if the result set is complete:

• the total number of results, which may be greater than the size of the result set (because a maximum result set size was specified) or may be unknown;
• the exception that terminated the query, if any.

This class maintains a global registry of all result sets. Result sets have fixed lifetimes (starting from completion time); a "reaper" thread may be started that periodically releases result sets whose lifetimes have expired. The reaper thread is also capable of compressing individual results that have not been accessed for a specified period of time.

All methods of this class are multithread-safe.

Version:

$Header: /export/home/gjanee/middleware/edu/ucsb/adl/middleware/RCS/ResultSet.java,v 1.5 2007/02/14 17:46:48 gjanee Exp $

$Log: ResultSet.java,v $ Revision 1.5 2007/02/14 17:46:48 gjanee
Added support for result set sharing. Added method reuse.

Revision 1.4 2004/03/15 17:54:40 gjanee
Added support for compression of results. Added an autoCompress argument to the constructor and a compressionAge argument to method startReaper. Rewrote the reaper logic to avoid a potential deadlock problem. Fixed a bug that was causing the reaper to hold on to released result sets for an extra cycle.

Revision 1.3 2004/03/05 23:29:43 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.2 2003/06/05 22:31:19 gjanee
Query results are now Result objects, i.e., triplets of standard metadata views.

Revision 1.1 1999/12/03 00:19:04 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Constructor Summary

ResultSet(edu.ucsb.adl.middleware.Global global, edu.ucsb.adl.middleware.Query query, long lifetime, boolean autoCompress)
Constructs a result set.

Method Summary

void	addResult(edu.ucsb.adl.middleware.Result result) Adds a result to the result set.
void	addResults(edu.ucsb.adl.middleware.Result[] results) Adds an array of results to the result set.
static edu.ucsb.adl.middleware.ResultSet[]	getAllInstances(edu.ucsb.adl.middleware.Global global) Returns all result sets in the global registry.
long	getCompletionTime() Returns the result set's completion time.
long	getCreationTime() Returns the result set's creation time.
java.lang.Exception	getException() Returns the exception that terminated the associated query.
int	getID() Returns the result set's ID.
static edu.ucsb.adl.middleware.ResultSet	getInstance(edu.ucsb.adl.middleware.Global global, int id) Locates a result set in the global registry.
int	getNumResults() Returns the current number of results in the result set.
edu.ucsb.adl.middleware.Query	getQuery() Returns the query associated with the result set.
edu.ucsb.adl.middleware.Result	getResult(int index) Returns a result from the result set.
edu.ucsb.adl.middleware.Result[]	getResults(int from, int to) Returns a range of results from the result set.
int	getTotalResultCount() Returns the total result count.
boolean	isComplete() Tests if the result set is complete.
void	release() Removes the result set from the global registry.
static edu.ucsb.adl.middleware.ResultSet	reuse(edu.ucsb.adl.middleware.Global global, edu.ucsb.adl.middleware.Query query) Returns an existing result set whose associated query exactly textually matches a given query, or returns null.
void	setComplete(int totalResultCount, java.lang.Exception exception) Signals that the result set is complete.
static void	startReaper(edu.ucsb.adl.middleware.Global global, long cycleTime, long compressionAge) Starts the reaper thread.
void	waitForCompletion() Returns when the result set is complete.

Methods inherited from class java.lang.Object

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

Constructor Detail

ResultSet

public ResultSet(edu.ucsb.adl.middleware.Global global,
                 edu.ucsb.adl.middleware.Query query,
                 long lifetime,
                 boolean autoCompress)

Constructs a result set.

Parameters:

global - The global object representing this instance of the middleware.

query - The associated query.

lifetime - The result set's lifetime in milliseconds.

autoCompress - A boolean indicating if results should automatically be compressed as they are added to the result set.

Throws:

java.lang.NullPointerException - If global or query is null.

java.lang.IllegalArgumentException - If lifetime is negative.

java.lang.IllegalStateException - If all IDs are in use, which is highly unlikely.

Method Detail

getInstance

public static edu.ucsb.adl.middleware.ResultSet getInstance(edu.ucsb.adl.middleware.Global global,
                                                            int id)

Locates a result set in the global registry.

Parameters:

global - The global object representing this instance of the middleware.

id - The desired result set's ID.

Returns:

The result set or null if there is no such result set.

getAllInstances

public static edu.ucsb.adl.middleware.ResultSet[] getAllInstances(edu.ucsb.adl.middleware.Global global)

Returns all result sets in the global registry.

Parameters:

global - The global object representing this instance of the middleware.

Returns:

The result sets.

getID

public int getID()

Returns the result set's ID.

Returns:

The ID.

getCreationTime

public long getCreationTime()

Returns the result set's creation time.

Returns:

The time in the semantics of System.currentTimeMillis.

getQuery

public edu.ucsb.adl.middleware.Query getQuery()

Returns the query associated with the result set.

Returns:

The query.

getNumResults

public int getNumResults()

Returns the current number of results in the result set.

Returns:

The current number of results.

getResult

public edu.ucsb.adl.middleware.Result getResult(int index)

Returns a result from the result set.

Parameters:

index - The index of the result to return.

Returns:

The query result.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If index is out of bounds.

getResults

public edu.ucsb.adl.middleware.Result[] getResults(int from,
                                                   int to)

Returns a range of results from the result set.

Parameters:

from - The starting index, inclusive.

to - The ending index, exclusive.

Returns:

The query results.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If from or to are out of bounds or if from is greater than to.

addResult

public void addResult(edu.ucsb.adl.middleware.Result result)

Adds a result to the result set.

Parameters:

result - The query result.

Throws:

java.lang.NullPointerException - If result is null.

java.lang.IllegalStateException - If the result set is already complete.

addResults

public void addResults(edu.ucsb.adl.middleware.Result[] results)

Adds an array of results to the result set.

Parameters:

results - The results to add, i.e., an array of Results.

Throws:

java.lang.NullPointerException - If results is null or if any element of results is null.

java.lang.IllegalStateException - If the result set is already complete.

isComplete

public boolean isComplete()

Tests if the result set is complete.

Returns:

true if the result set is complete.

getCompletionTime

public long getCompletionTime()

Returns the result set's completion time.

Returns:

The time in the semantics of System.currentTimeMillis or a negative value if the result set is incomplete.

getTotalResultCount

public int getTotalResultCount()

Returns the total result count.

Returns:

The total result count, or a negative value if the total result count is unknown or the result set is incomplete.

getException

public java.lang.Exception getException()

Returns the exception that terminated the associated query.

Returns:

The exception, or null if the query completed successfully or the result set is incomplete.

setComplete

public void setComplete(int totalResultCount,
                        java.lang.Exception exception)

Signals that the result set is complete.

Parameters:

totalResultCount - The total number of results, or a negative value if the total number is unknown.

exception - The exception that terminated the associated query, or null if the query terminated successfully.

Throws:

java.lang.IllegalArgumentException - If totalResultCount is nonnegative and less than the current size of the result set.

java.lang.IllegalStateException - If the result set is already complete.

waitForCompletion

public void waitForCompletion()

Returns when the result set is complete.

release

public void release()

Removes the result set from the global registry. The result set is otherwise unchanged so that threads that are already referencing the result set may continue to do so without problem.

reuse

public static edu.ucsb.adl.middleware.ResultSet reuse(edu.ucsb.adl.middleware.Global global,
                                                      edu.ucsb.adl.middleware.Query query)

Returns an existing result set whose associated query exactly textually matches a given query, or returns null. If a result set is found, and if the result set is complete, its age is effectively reset to zero.

Parameters:

global - The global object representing this instance of the middleware.

query - The query to match.

Returns:

A ResultSet, or null.

startReaper

public static void startReaper(edu.ucsb.adl.middleware.Global global,
                               long cycleTime,
                               long compressionAge)

Starts the reaper thread. All calls to this method but the first (per middleware instance) are ignored.

Parameters:

global - The global object representing this instance of the middleware.

cycleTime - The duration of the reaper's cycle in milliseconds.

compressionAge - The age in milliseconds at which query results are compressed by the reaper. If negative, the reaper never compresses results. A query result's age is reset to zero each time a metadata view is requested from the result.

Throws:

java.lang.IllegalArgumentException - If cycleTime is negative.