org.protempa.dest

Interface QueryResultsHandler

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

AbstractQueryResultsHandler, DeidentifiedQueryResultsHandler, KeyLoaderQueryResultsHandler, MapQueryResultsHandler, PropositionListQueryResultsHandler, TableQueryResultsHandler, XmlQueryResultsHandler

public interface QueryResultsHandler
extends AutoCloseable

Interface defining the operations for handling results of a Protempa query. Protempa calls the methods of a provided implementation of this interface in the following order:

1. #start()
2. handleQueryResult(java.lang.String, java.util.List, java.util.Map, java.util.Map, java.util.Map) called once per key
3. finish()
4. close()

If an exception is thrown by #start() or handleQueryResult(java.lang.String, java.util.List, java.util.Map, java.util.Map, java.util.Map), finish() will be skipped. If cancel() is called before finish() is called, the latter will be skipped. The cancel() method may be called in parallel with execution of any of the other methods in the interface. The different methods of this interface may be called by different (albeit synchronized) threads.

Author:

Michel Mansour

Method Summary

Modifier and Type	Method and Description
void	cancel() Requests cancellation of whatever this object is currently doing.
void	close() Called by Protempa after #handleFinish() to clean up any resources used by the handler.
void	finish() Called by Protempa as soon as all query results have been retrieved from the data source.
String	getDisplayName() Gets the query result handler's display name for user interfaces.
String	getId() Gets the query result handler's identifier string for logging and internal purposes.
void	handleQueryResult(String keyId, List<Proposition> propositions, Map<Proposition,List<Proposition>> forwardDerivations, Map<Proposition,List<Proposition>> backwardDerivations, Map<UniqueId,Proposition> references) Handles a single query result, which is the list of propositions associated with the given key.
void	start(Collection<PropositionDefinition> cache) Called by Protempa prior to the first invocation of handleQueryResult(java.lang.String, java.util.List, java.util.Map, java.util.Map, java.util.Map).
void	validate() Validates this query results handler's specification.

Method Detail

getId

String getId()

Gets the query result handler's identifier string for logging and internal purposes.

Returns:

a string.

getDisplayName

String getDisplayName()

Gets the query result handler's display name for user interfaces.

Returns:

a string.

validate

void validate()
       throws QueryResultsHandlerValidationFailedException

Validates this query results handler's specification.

Throws:

QueryResultsHandlerValidationFailedException - if validation failed.

start

void start(Collection<PropositionDefinition> cache)
    throws QueryResultsHandlerProcessingException

Called by Protempa prior to the first invocation of handleQueryResult(java.lang.String, java.util.List, java.util.Map, java.util.Map, java.util.Map). Implementers of this method may perform arbitrary processing related to the output of the handler, such as printing out headers of a file or extracting metadata for the handler's output.

Parameters:

cache - a cache of all of the proposition definitions that were queried.

Throws:

QueryResultsHandlerProcessingException - if any exceptions occur at a lower level.

handleQueryResult

void handleQueryResult(String keyId,
                       List<Proposition> propositions,
                       Map<Proposition,List<Proposition>> forwardDerivations,
                       Map<Proposition,List<Proposition>> backwardDerivations,
                       Map<UniqueId,Proposition> references)
                throws QueryResultsHandlerProcessingException

Handles a single query result, which is the list of propositions associated with the given key.

Parameters:

keyId - the identifying key id for the result

propositions - the proposition results for the given key as a newly created List.

derivationsList - a mapping from propositions to derived abstractions. and propositions.

Throws:

QueryResultsHandlerProcessingException

finish

void finish()
     throws QueryResultsHandlerProcessingException

Called by Protempa as soon as all query results have been retrieved from the data source. Will not be called if a previous step failed.

Throws:

QueryResultsHandlerProcessingException - if any exceptions occur at a lower level

close

void close()
    throws QueryResultsHandlerCloseException

Called by Protempa after #handleFinish() to clean up any resources used by the handler. It is called always, even if a previous step failed.

Specified by:

close in interface AutoCloseable

Throws:

QueryResultsHandlerCloseException - if any exceptions occur at a lower level

cancel

void cancel()

Requests cancellation of whatever this object is currently doing. If finish() has not been called yet, it will be skipped. If close() has not been called yet, it will be called, and it must finish cleaning up all resources associated with this query results handler.