edu.ucsb.adl.middleware
Class ResultAccumulator

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

Direct Known Subclasses:

PassthruAccumulator, RankingAccumulator

public abstract class ResultAccumulator

extends java.lang.Object

Abstract base class of all query result accumulators. An accumulator accumulates query results from multiple "source threads" and adds them to its associated result set. Concrete subclasses of this class implement different policies by which the results are added to the result set. For example, some subclasses perform ranking and culling of results before adding them to the result set.

Source threads must call method sourceTerminated upon termination. Conversely, this class requests that source threads terminate, and the associated result set is marked as being complete, when:

• Any source thread terminates with an exception.
• The last remaining source thread terminates normally.
• The accumulator times out.
• The maximum number of results requested by the query is reached.
• The accumulator's maximum number of results is exceeded.
• The destroy method is called.

This class maintains a global registry of all accumulators. Accumulators are identified by integer IDs that match the IDs of the associated result sets.

This class is multithread-safe.

Version:

$Header: /export/home/gjanee/middleware/edu/ucsb/adl/middleware/RCS/ResultAccumulator.java,v 1.6 2006/06/23 01:28:22 gjanee Exp $

$Log: ResultAccumulator.java,v $ Revision 1.6 2006/06/23 01:28:22 gjanee
Added support for metadata caching. If a metadata report starts with the string "VALID", it is assumed to have come from a cache, and since only valid and processed reports are cached, all further validation and processing of the report is sidestepped.

Revision 1.5 2004/09/14 19:58:24 gjanee
Improved an error message.

Revision 1.4 2004/03/05 19:30: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 20:53:19 gjanee
Query results are now Result objects, i.e., triplets of standard metadata views. Added code to remove encoding declarations in query result metadata views. Also, added validation of query results.

Revision 1.2 2001/11/16 16:56:04 gjanee
Minor documentation change to reflect new internationalization requirements.

Revision 1.1 2000/01/28 21:25:12 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Field Summary

protected int	m_maximumResults The maximum number of results to accumulate.
protected edu.ucsb.adl.middleware.ResultSet	m_set The associated result set, or null if the accumulator has been destroyed.

Constructor Summary

ResultAccumulator(edu.ucsb.adl.middleware.Global global, edu.ucsb.adl.middleware.ResultSet set, int maximumResults, long lifetime, boolean validateResults)
Creates a ResultAccumulator.

Method Summary

void	addResult(edu.ucsb.adl.middleware.Result result) Adds a result to the accumulator.
protected abstract void	addResultInternal(edu.ucsb.adl.middleware.Result result) Should add a result to the accumulator.
void	addSource(edu.ucsb.adl.middleware.QueryThread source) Registers a source thread with the accumulator.
void	destroy(java.lang.Exception exception) Destroys the accumulator, stops all source threads, and marks the associated result set as being complete.
protected abstract void	flushToResultSet() Should flush all results out of the accumulator and into the associated result set.
static edu.ucsb.adl.middleware.ResultAccumulator[]	getAllInstances(edu.ucsb.adl.middleware.Global global) Returns all accumulators in the global registry.
int	getID() Returns the accumulator's ID.
static edu.ucsb.adl.middleware.ResultAccumulator	getInstance(edu.ucsb.adl.middleware.Global global, int id) Locates an accumulator in the global registry.
edu.ucsb.adl.middleware.QueryThread[]	getOutstandingSources() Returns the accumulator's outstanding source threads.
protected abstract int	getTotalResultCount() Should return the total result count.
boolean	isStarted() Tests if the accumulator has been started.
void	sourceTerminated(edu.ucsb.adl.middleware.QueryThread source, java.lang.Exception exception) Signals that a source thread has terminated.
void	start() Starts the accumulator, the accumulator's timeout thread, and all source threads.

Methods inherited from class java.lang.Object

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

Field Detail

m_set

protected edu.ucsb.adl.middleware.ResultSet m_set

The associated result set, or null if the accumulator has been destroyed.

m_maximumResults

protected int m_maximumResults

The maximum number of results to accumulate.

Constructor Detail

ResultAccumulator

public ResultAccumulator(edu.ucsb.adl.middleware.Global global,
                         edu.ucsb.adl.middleware.ResultSet set,
                         int maximumResults,
                         long lifetime,
                         boolean validateResults)

Creates a ResultAccumulator.

Parameters:

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

set - The associated result set. The result set should be incomplete, and no object other than the accumulator should ever mark it as being complete.

maximumResults - The maximum number of results to accumulate. Note that this is independent of the maximum number of results requested in the associated query.

lifetime - The lifetime of the accumulator in milliseconds.

validateResults - Indicates if query results should be validated.

Throws:

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

java.lang.IllegalArgumentException - If maximumResults or lifetime are negative.

Method Detail

getInstance

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

Locates an accumulator in the global registry.

Parameters:

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

id - The desired accumulator's ID.

Returns:

The accumulator or null if there is no such accumulator.

getAllInstances

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

Returns all accumulators in the global registry.

Parameters:

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

Returns:

The accumulators.

getID

public int getID()

Returns the accumulator's ID.

Returns:

The ID.

getOutstandingSources

public edu.ucsb.adl.middleware.QueryThread[] getOutstandingSources()

Returns the accumulator's outstanding source threads. If the accumulator has been destroyed, an empty array is returned.

Returns:

The source threads.

isStarted

public boolean isStarted()

Tests if the accumulator has been started.

Returns:

true if the accumulator has been started.

addSource

public void addSource(edu.ucsb.adl.middleware.QueryThread source)

Registers a source thread with the accumulator.

Parameters:

source - The source thread, which should not have been started yet.

Throws:

java.lang.NullPointerException - If source is null.

java.lang.IllegalStateException - If the accumulator has already been started or destroyed.

start

public void start()

Starts the accumulator, the accumulator's timeout thread, and all source threads.

Throws:

java.lang.IllegalStateException - If the accumulator has already been started or destroyed.

addResult

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

Adds a result to the accumulator.

Parameters:

result - The result. The result's metadata views should not contain encoding declarations.

Throws:

java.lang.NullPointerException - If result is null.

java.lang.IllegalStateException - If the accumulator has not been started yet.

sourceTerminated

public void sourceTerminated(edu.ucsb.adl.middleware.QueryThread source,
                             java.lang.Exception exception)

Signals that a source thread has terminated.

Parameters:

source - The source thread.

exception - The exception that terminated the thread, or null if the thread terminated normally.

Throws:

java.lang.NullPointerException - If source is null.

java.lang.IllegalArgumentException - If source was never registered with the accumulator.

java.lang.IllegalStateException - If the accumulator has not been started yet.

destroy

public void destroy(java.lang.Exception exception)

Destroys the accumulator, stops all source threads, and marks the associated result set as being complete.

Parameters:

exception - The reason for the accumulator's destruction or null.

addResultInternal

protected abstract void addResultInternal(edu.ucsb.adl.middleware.Result result)

Should add a result to the accumulator. It is guaranteed that result is not null and that the accumulator has been started and not yet destroyed. The implementing method can signal an error by destroying the accumulator with an appropriate exception.

Parameters:

result - The result.

flushToResultSet

protected abstract void flushToResultSet()

Should flush all results out of the accumulator and into the associated result set. This method is called, exactly once, during the destruction of the accumulator.

getTotalResultCount

protected abstract int getTotalResultCount()

Should return the total result count. This method is called, exactly once, during the destruction of the accumulator, and then only if all source threads terminated normally.