org.protempa

Class Protempa

java.lang.Object

org.protempa.Protempa

All Implemented Interfaces:

AutoCloseable

public final class Protempa
extends Object
implements AutoCloseable

Main PROTEMPA API.

Author:

Andrew Post

Constructor Summary

Constructors

Constructor and Description
Protempa(DataSource dataSource, KnowledgeSource knowledgeSource, AlgorithmSource algorithmSource, TermSource termSource) Constructor that configures PROTEMPA not to cache found abstract parameters.
Protempa(DataSource dataSource, KnowledgeSource knowledgeSource, AlgorithmSource algorithmSource, TermSource termSource, boolean cacheFoundAbstractParameters) Constructor that lets the user specify whether or not to cache found abstract parameters.

Method Summary

Modifier and Type	Method and Description
void	addEventListener(ProtempaEventListener eventListener)
Query	buildQuery(QueryBuilder queryBuilder) Convenience method for calling QueryBuilder.build(org.protempa.KnowledgeSource, org.protempa.AlgorithmSource) with this Protempa instance's knowledge source and algorithm source.
void	cancel() Cancels an executing query.
void	clear() Clears resources created by this object and the data source, knowledge source and algorithm source.
void	close() Closes resources created by this object and the data source, knowledge source, and algorithm source.
void	execute(Query query, Destination destination) Executes a query.
AlgorithmSource	getAlgorithmSource() Gets the algorithm source.
DataSource	getDataSource() Gets the data source.
KnowledgeSource	getKnowledgeSource() Gets the knowledge source.
String[]	getSupportedPropositionIds(Destination destination)
TermSource	getTermSource() Gets the term source.
static Protempa	newInstance(SourceFactory sourceFactory)
static Protempa	newInstance(SourceFactory sourceFactory, boolean useCache)
static Protempa	newInstance(String configurationId)
static Protempa	newInstance(String configurationsId, boolean useCache)
void	removeEventListener(ProtempaEventListener eventListener)
void	validateDataSourceBackendConfigurations()
DataValidationEvent[]	validateDataSourceBackendData() Runs each data source backend's data validation routine.

Methods inherited from class java.lang.Object

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

Constructor Detail

Protempa

public Protempa(DataSource dataSource,
                KnowledgeSource knowledgeSource,
                AlgorithmSource algorithmSource,
                TermSource termSource)
         throws ProtempaStartupException

Constructor that configures PROTEMPA not to cache found abstract parameters.

Parameters:

dataSource - a DataSource. Will be closed when close() is called. May be null if you're not retrieving data from a data source (for example, you're only working with a persistent store).

knowledgeSource - a KnowledgeSource. Will be closed when close() is called.

algorithmSource - an AlgorithmSource. Will be closed when close() is called. May be null if you're not computing any low-level abstractions.

termSource - a TermSource. Will be closed when close() is called. May be null if you're not using terms.

Throws:

ProtempaStartupException - if an error occur in starting Protempa. There frequently will be a nested exception that provides more detail.

Protempa

public Protempa(DataSource dataSource,
                KnowledgeSource knowledgeSource,
                AlgorithmSource algorithmSource,
                TermSource termSource,
                boolean cacheFoundAbstractParameters)
         throws ProtempaStartupException

Constructor that lets the user specify whether or not to cache found abstract parameters.

Parameters:

dataSource - a DataSource. Will be closed when close() is called. May be null if you're not retrieving data from a data source (for example, you're only working with a persistent store).

knowledgeSource - a KnowledgeSource. Will be closed when close() is called.

algorithmSource - an AlgorithmSource. Will be closed when close() is called. May be null if you're not computing any low-level abstractions.

termSource - a TermSource. Will be closed when close() is called. May be null if you're not using terms.

cacheFoundAbstractParameters - true to cache found abstract parameters, false not to cache found abstract parameters.

Throws:

ProtempaStartupException - if an error occur in starting Protempa. There frequently will be a nested exception that provides more detail.

Method Detail

newInstance

public static Protempa newInstance(String configurationId)
                            throws ProtempaStartupException

Throws:

ProtempaStartupException

newInstance

public static Protempa newInstance(SourceFactory sourceFactory)
                            throws ProtempaStartupException

Throws:

ProtempaStartupException

newInstance

public static Protempa newInstance(String configurationsId,
                                   boolean useCache)
                            throws ProtempaStartupException

Throws:

ProtempaStartupException

newInstance

public static Protempa newInstance(SourceFactory sourceFactory,
                                   boolean useCache)
                            throws ProtempaStartupException

Throws:

ProtempaStartupException

getDataSource

public DataSource getDataSource()

Gets the data source.

Returns:

a DataSource. Will be closed when close() is called.

getKnowledgeSource

public KnowledgeSource getKnowledgeSource()

Gets the knowledge source.

Returns:

a KnowledgeSource. Will be closed when close() is called.

getAlgorithmSource

public AlgorithmSource getAlgorithmSource()

Gets the algorithm source.

Returns:

an AlgorithmSource. Will be closed when close() is called.

getTermSource

public TermSource getTermSource()

Gets the term source.

Returns:

a TermSource. Will be closed when close() is called

addEventListener

public void addEventListener(ProtempaEventListener eventListener)

removeEventListener

public void removeEventListener(ProtempaEventListener eventListener)

buildQuery

public Query buildQuery(QueryBuilder queryBuilder)
                 throws QueryBuildException

Convenience method for calling QueryBuilder.build(org.protempa.KnowledgeSource, org.protempa.AlgorithmSource) with this Protempa instance's knowledge source and algorithm source.

Parameters:

queryBuilder - a query specification.

Returns:

the query.

Throws:

QueryBuildException - if the query specification failed validation or some other error occurred.

getSupportedPropositionIds

public String[] getSupportedPropositionIds(Destination destination)
                                    throws GetSupportedPropositionIdsException

Throws:

GetSupportedPropositionIdsException

execute

public void execute(Query query,
                    Destination destination)
             throws QueryException

Executes a query. Protempa determines which propositions to retrieve from the underlying data sources and compute as the union of the proposition ids specified in the supplied Query and the proposition ids returned from the results handler's QueryResultsHandler#getPropositionIdsNeeded() method.

Parameters:

query - a Query. Cannot be null.

destination - a destination. Cannot be null.

Throws:

QueryException - if an error occurred during query.

cancel

public void cancel()

Cancels an executing query. If a query is not running, this method has no effect. Is intended to be called from a different thread from the one that called execute(org.protempa.query.Query, org.protempa.dest.Destination).

validateDataSourceBackendConfigurations

public void validateDataSourceBackendConfigurations()
                                             throws DataSourceValidationIncompleteException,
                                                    DataSourceFailedConfigurationValidationException

Throws:

DataSourceValidationIncompleteException

DataSourceFailedConfigurationValidationException

validateDataSourceBackendData

public DataValidationEvent[] validateDataSourceBackendData()
                                                    throws DataSourceFailedDataValidationException,
                                                           DataSourceValidationIncompleteException

Runs each data source backend's data validation routine.

Throws:

DataSourceFailedDataValidationException - if validation failed.

DataSourceValidationIncompleteException - if an error occurred during validation that prevented its completion.

close

public void close()
           throws CloseException

Closes resources created by this object and the data source, knowledge source, and algorithm source.

Specified by:

close in interface AutoCloseable

Throws:

CloseException - if an error occurs while closing resources.

clear

public void clear()

Clears resources created by this object and the data source, knowledge source and algorithm source.