org.jamesframework.core.search.stopcriteria

Class StopCriterionChecker

java.lang.Object

org.jamesframework.core.search.stopcriteria.StopCriterionChecker

public class StopCriterionChecker
extends Object

A stop criterion checker is responsible for checking the stop criteria of a given search, while this search is running. At construction, a reference to the search is given. Stop criteria can be added using add(StopCriterion), which usually only happens from within the search, which passes all its stop criteria to its dedicated checker.

When startChecking() is called, a task will be scheduled to periodically check the stop criteria in the background, by default with a period of 1 second, while the search is running. These tasks are executed by a dedicated thread which is shared among all stop criterion checker instances, as checking stop criteria is not an intensive task. A manual check can be performed with stopCriterionSatisfied().

As soon as some stop criterion is satisfied, the checker will cancel the scheduled task for further execution and will request the search to stop.

Author:

Herman De Beukelaer

Constructor Summary

Constructors

Constructor and Description
StopCriterionChecker(Search<?> search) Create a stop criterion checker dedicated to checking the stop criteria of the given search.

Method Summary

Modifier and Type	Method and Description
void	add(StopCriterion stopCriterion) Add a stop criterion to check.
void	clear() Remove all stop criteria.
boolean	remove(StopCriterion stopCriterion) Remove a stop criterion.
void	setPeriod(long period, TimeUnit timeUnit) Set the period between consecutive stop criterion checks.
void	startChecking() Start checking the stop criteria, in a separate background thread.
void	stopChecking() Instructs the stop criterion checker to stop checking.
boolean	stopCriterionSatisfied() Check whether at least one stop criterion is satisfied.

Methods inherited from class java.lang.Object

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

Constructor Detail

StopCriterionChecker

public StopCriterionChecker(Search<?> search)

Create a stop criterion checker dedicated to checking the stop criteria of the given search. By default, consecutive checks will be separated with a period of 1 second. This can be customized using setPeriod(long, TimeUnit).

Parameters:

search - search for which the stop criteria should be checked while running

Method Detail

add

public void add(StopCriterion stopCriterion)

Add a stop criterion to check.

Parameters:

stopCriterion - stop criterion to add

Throws:

IncompatibleStopCriterionException - if the given stop criterion is not compatible with the search to which this checker belongs

remove

public boolean remove(StopCriterion stopCriterion)

Remove a stop criterion. Returns false if the given stop criterion had never been added.

Parameters:

stopCriterion - stop criterion to remove

Returns:

true if the stop criterion has successfully been removed

clear

public void clear()

Remove all stop criteria.

setPeriod

public void setPeriod(long period,
                      TimeUnit timeUnit)

Set the period between consecutive stop criterion checks. By default, this period is set to 1 second. The new settings will apply as from the next call of startChecking().

Parameters:

period - period between two checks

timeUnit - time unit of this period

startChecking

public void startChecking()

Start checking the stop criteria, in a separate background thread. If the stop criterion checker is already active, or if no stop criteria have been added, calling this method does not have any effect.

stopChecking

public void stopChecking()

Instructs the stop criterion checker to stop checking. In case the checker is not active, calling this method does not have any effect.

stopCriterionSatisfied

public boolean stopCriterionSatisfied()

Check whether at least one stop criterion is satisfied.

Returns:

true if a stop condition is satisfied