net.ssehub.easy.reasoning.core.frontend

Class ReasonerFrontend

java.lang.Object

net.ssehub.easy.reasoning.core.frontend.ReasonerFrontend

public class ReasonerFrontend
extends java.lang.Object

The main interface to the reasoner core infrastructure. Models and configurations will be transparently passed to matching reasoners.

Author:

Patrick J�hne, Sascha El-Sharkawy, Holger Eichelberger

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	ReasonerFrontend.DefaultReasonerProvider Implements the default reasoner provider.

Field Summary

Fields

Modifier and Type	Field and Description
private static ReasonerFrontend	INSTANCE
private static java.lang.String	NO_REASONING_AVAILABE_MSG
private IReasoner	reasonerHint
private ReasonerRegistry	registry
private int	timeout

Constructor Summary

Constructors

Modifier	Constructor and Description
private	ReasonerFrontend() Singleton constructor for this class.

Method Summary

Modifier and Type	Method and Description
private static IReasoner	canInitializeConfig(IReasoner reasoner) Checks reasoner for GeneralReasonerCapabilities.CONFIGURATION_INITIALIZATION.
ReasoningResult	check(net.ssehub.easy.varModel.confModel.Configuration cfg, ReasonerConfiguration reasonerConfiguration, net.ssehub.easy.basics.progress.ProgressObserver observer) Checks the configuration according to the given project structure and does not affect the configuration.
private static IReasoner	checkForCapabilitiy(IReasoner reasoner, net.ssehub.easy.varModel.capabilities.IReasonerCapability capability) Checks reasoner for the given reasoner capability.
IReasonerInstance	createInstance(net.ssehub.easy.varModel.confModel.Configuration cfg, ReasonerConfiguration reasonerConfiguration) Creates a reasoner instance for repeated reasoning on the same model (no structural changes allowed during two subsequent reasoning runs).
ValueCreationResult	createValue(net.ssehub.easy.varModel.confModel.Configuration cfg, net.ssehub.easy.varModel.model.AbstractVariable var, net.ssehub.easy.varModel.model.datatypes.IDatatype type, ReasonerConfiguration reasonerConfiguration, net.ssehub.easy.basics.progress.ProgressObserver observer) Creates the value for a certain IVML type/variable.
EvaluationResult	evaluate(net.ssehub.easy.varModel.confModel.Configuration cfg, java.util.List<net.ssehub.easy.varModel.model.Constraint> constraints, ReasonerConfiguration reasonerConfiguration, net.ssehub.easy.basics.progress.ProgressObserver observer) Evaluates a given list of constraints (in the sense of boolean conditions) which are related to and valid in the context of the given project and configuration.
(package private) IReasoner	findReasoner(ReasonerDescriptor descriptor) Finds a reasoner and throws related exceptions.
IReasoner	findReasoner(java.lang.String name, java.lang.String version) Returns the first version with given name and version.
private IReasoner	getActualReasoner(net.ssehub.easy.varModel.confModel.Configuration configuration, java.util.List<net.ssehub.easy.varModel.model.Constraint> constraints, ReasonerConfiguration reasonerConfiguration) Returns the actual and matching reasoner.
static ReasonerFrontend	getInstance() Returns the singleton instance of this class.
ReasonerDescriptor	getPreferredReasoner() Returns the preferred reasoner descriptor due to internal knowledge about the reasoner implementation status.
int	getReadyForUseCount() Returns the number of reasoners which are ready for use.
ReasonerDescriptor	getReasonerDescriptor(int index) Returns the descriptor for a specific reasoner.
ReasonerDescriptor	getReasonerHint() Returns the current reasoner hint.
int	getReasonersCount() Returns the number of available reasoners.
IReasonerRegistry	getRegistry() Getter for the Reasoner registry, capable of handling multiple IReasoners.
int	getTimeout() Returns the global timeout for reasoning.
boolean	hasReasonerCapability(net.ssehub.easy.varModel.capabilities.IReasonerCapability capability) Return whether the current reasoner hint has a specific capability.
boolean	hasReasonerCapability(net.ssehub.easy.varModel.capabilities.IReasonerCapability capability, ReasonerConfiguration reasonerConfiguration) Return whether the current reasoner hint has a specific capability.
private void	installConfigurationInitializer() Installs the configuration intializer.
boolean	isChainingReasoner(ReasonerDescriptor descriptor) Returns whether the reasoner registered for this descriptor is a chaining reasoner.
ReasoningResult	isConsistent(net.ssehub.easy.varModel.model.Project project, ReasonerConfiguration reasonerConfiguration, net.ssehub.easy.basics.progress.ProgressObserver observer) Checks whether a given variability model (project) is satisfiable.
private static boolean	isReadyForUse(IReasoner reasoner) Returns whether the given reasoner is ready for use.
ReasoningResult	propagate(net.ssehub.easy.varModel.confModel.Configuration cfg, ReasonerConfiguration reasonerConfiguration, net.ssehub.easy.basics.progress.ProgressObserver observer) Checks the configuration according to the given model and propagates values, if possible.
boolean	reasoningSupported() Checks whether at least one reasoner is present.
void	register(IMessageListener listener) Registers a message listener.
ReasonerDescriptor	setPreferredReasoner() Sets the actually preferred reasoner as hint.
void	setReasonerHint(ReasonerDescriptor descriptor) Defines that the specified reasoner shall be used.
void	setTimeout(int timeout) Changes the global timeout for reasoning.
void	unregister(IMessageListener listener) Unregisters a message listener.
ReasoningResult	upgradeReasoner(ReasonerDescriptor descriptor, java.net.URI uri, net.ssehub.easy.basics.progress.ProgressObserver observer) Updates a reasoner installation, e.g., in order to obtain a licensed reasoner version.

Methods inherited from class java.lang.Object

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

Field Detail

NO_REASONING_AVAILABE_MSG

private static final java.lang.String NO_REASONING_AVAILABE_MSG

See Also:

Constant Field Values

INSTANCE

private static final ReasonerFrontend INSTANCE

registry

private ReasonerRegistry registry

reasonerHint

private IReasoner reasonerHint

timeout

private int timeout

Constructor Detail

ReasonerFrontend

private ReasonerFrontend()

Singleton constructor for this class.

Method Detail

installConfigurationInitializer

private void installConfigurationInitializer()

Installs the configuration intializer.

canInitializeConfig

private static IReasoner canInitializeConfig(IReasoner reasoner)

Checks reasoner for GeneralReasonerCapabilities.CONFIGURATION_INITIALIZATION.

Parameters:

reasoner - the reasoner to check

Returns:

reasoner if capability is provided, null else

See Also:

checkForCapabilitiy(IReasoner, IReasonerCapability)

checkForCapabilitiy

private static IReasoner checkForCapabilitiy(IReasoner reasoner,
                                             net.ssehub.easy.varModel.capabilities.IReasonerCapability capability)

Checks reasoner for the given reasoner capability.

Parameters:

reasoner - the reasoner to check

capability - the capability to check for

Returns:

reasoner if capability is provided, null else

getInstance

public static final ReasonerFrontend getInstance()

Returns the singleton instance of this class.

Returns:

The singleton instance of this class

getRegistry

public IReasonerRegistry getRegistry()

Getter for the Reasoner registry, capable of handling multiple IReasoners.

Returns:

The IReasonerRegistry used by this frontend.

getActualReasoner

private IReasoner getActualReasoner(net.ssehub.easy.varModel.confModel.Configuration configuration,
                                    java.util.List<net.ssehub.easy.varModel.model.Constraint> constraints,
                                    ReasonerConfiguration reasonerConfiguration)

Returns the actual and matching reasoner. Considers whether the reasoner is ready for use via ReasonerDescriptor.isReadyForUse().

Parameters:

configuration - the configuration to reason on (may be null)

constraints - the additional constraints to reason on (may be null)

reasonerConfiguration - the configuration to be used for the specific reasoner call (may be null)

Returns:

the actual reasoner (may be null)

isReadyForUse

private static boolean isReadyForUse(IReasoner reasoner)

Returns whether the given reasoner is ready for use.

Parameters:

reasoner - the reasoner to check for

Returns:

true if reasoner is ready for use, false else

See Also:

ReasonerDescriptor.isReadyForUse()

isConsistent

public ReasoningResult isConsistent(net.ssehub.easy.varModel.model.Project project,
                                    ReasonerConfiguration reasonerConfiguration,
                                    net.ssehub.easy.basics.progress.ProgressObserver observer)

Checks whether a given variability model (project) is satisfiable.

Parameters:

project - The project which should be tested whether it is satisfiable.

reasonerConfiguration - the reasoner configuration to be used for reasoning (e.g. taken from the UI, may be null)

observer - a progress observer indicating the progress, use ProgressObserver.NO_OBSERVER if no progress shall be indicated

Returns:

The result of this reasoning step. Can have the status Status.UNSUPPORTED if the concrete reasoner does not support this operation.

check

public ReasoningResult check(net.ssehub.easy.varModel.confModel.Configuration cfg,
                             ReasonerConfiguration reasonerConfiguration,
                             net.ssehub.easy.basics.progress.ProgressObserver observer)

Checks the configuration according to the given project structure and does not affect the configuration. Takes the project from the configuration. Corresponding method with project and configuration may become deprecated/disappear in future.

Parameters:

cfg - The current configuration based on the given project.

reasonerConfiguration - the reasoner configuration to be used for reasoning (e.g. taken from the UI, may be null)

observer - a progress observer indicating the progress, use ProgressObserver.NO_OBSERVER if no progress shall be indicated

Returns:

The result of this reasoning step. Can have the status Status.UNSUPPORTED if the concrete reasoner does not support this operation.

See Also:

#check(Project, Configuration, ReasonerConfiguration, ProgressObserver)

propagate

public ReasoningResult propagate(net.ssehub.easy.varModel.confModel.Configuration cfg,
                                 ReasonerConfiguration reasonerConfiguration,
                                 net.ssehub.easy.basics.progress.ProgressObserver observer)

Checks the configuration according to the given model and propagates values, if possible. Takes the project from the configuration. Corresponding method with project and configuration may become deprecated/disappear in future.

Parameters:

cfg - The current configuration based on the given project. (may be modified as a side effect of value propagation)

observer - a progress observer indicating the progress, use ProgressObserver.NO_OBSERVER if no progress shall be indicated

reasonerConfiguration - the reasoner configuration to be used for reasoning (e.g. taken from the UI, may be null)

Returns:

The result of this reasoning step. Can have the status Status.UNSUPPORTED if the concrete reasoner does not support this operation.

See Also:

#propagate(Project, Configuration, ReasonerConfiguration, ProgressObserver)

evaluate

public EvaluationResult evaluate(net.ssehub.easy.varModel.confModel.Configuration cfg,
                                 java.util.List<net.ssehub.easy.varModel.model.Constraint> constraints,
                                 ReasonerConfiguration reasonerConfiguration,
                                 net.ssehub.easy.basics.progress.ProgressObserver observer)

Evaluates a given list of constraints (in the sense of boolean conditions) which are related to and valid in the context of the given project and configuration. Takes the project from the configuration. Corresponding method with project and configuration may become deprecated/disappear in future.

Parameters:

cfg - the configuration as a basis for the evaluation

constraints - the constraints (expressions which must evaluate to true)

reasonerConfiguration - the reasoner configuration to be used for reasoning (e.g. taken from the UI, may be null)

observer - a progress observer indicating the progress, use ProgressObserver.NO_OBSERVER if no progress shall be indicated

Returns:

The result of this reasoning step. The result pairs may be given in a different order than in constraints. null constraints are ignored and not returned as a result. Can have the status Status.UNSUPPORTED if the concrete reasoner does not support this operation.

See Also:

#evaluate(Project, Configuration, List, ReasonerConfiguration, ProgressObserver)

getReadyForUseCount

public int getReadyForUseCount()

Returns the number of reasoners which are ready for use. Contrary to getReasonersCount(), this method counts only reasoners which can be used for reasoning. This number is ≤ to getReasonersCount().

Returns:

the number of reasoners which are ready for use

See Also:

getReasonersCount()

getReasonersCount

public int getReasonersCount()

Returns the number of available reasoners. This method counts also reasoners which are installed but cannot be used for reasoning, e.g. no license available.

Returns:

the number of available reasoners

See Also:

getReadyForUseCount()

getReasonerDescriptor

public ReasonerDescriptor getReasonerDescriptor(int index)

Returns the descriptor for a specific reasoner.

Parameters:

index - the index of the reasoner

Returns:

the descriptor

Throws:

java.lang.IndexOutOfBoundsException - in case that index<0 || index>={getReasonersCount()

upgradeReasoner

public ReasoningResult upgradeReasoner(ReasonerDescriptor descriptor,
                                       java.net.URI uri,
                                       net.ssehub.easy.basics.progress.ProgressObserver observer)

Updates a reasoner installation, e.g., in order to obtain a licensed reasoner version.

Parameters:

descriptor - the descriptor of the reasoner to be updated

uri - the URI where the data for the upgrade is located at

observer - an optional progress observer, shall be ProgressObserver.NO_OBSERVER if unused

Returns:

The result of this reasoning step. Can have the status Status.UNSUPPORTED if the concrete reasoner does not support this operation.

Throws:

java.lang.IllegalArgumentException - in case of illegal arguments

setReasonerHint

public void setReasonerHint(ReasonerDescriptor descriptor)

Defines that the specified reasoner shall be used. Note that this method only defines a hint. In case of automated selection of reasoners, this class may ignore the specified information. Please note that this method stores the selected reasoner just within the reasoner frontend and does not persist this selection.

Parameters:

descriptor - the descriptor denoting the reasoner (may be null for clearing an already set hint)

Throws:

java.lang.IllegalArgumentException - in case of illegal arguments

hasReasonerCapability

public boolean hasReasonerCapability(net.ssehub.easy.varModel.capabilities.IReasonerCapability capability)

Return whether the current reasoner hint has a specific capability. [convenience]

Parameters:

capability - the capability to look for

Returns:

true if the capability is provided, false else

hasReasonerCapability

public boolean hasReasonerCapability(net.ssehub.easy.varModel.capabilities.IReasonerCapability capability,
                                     ReasonerConfiguration reasonerConfiguration)

Return whether the current reasoner hint has a specific capability. [convenience]

Parameters:

capability - the capability to look for

reasonerConfiguration - the configuration to consider (may be null)

Returns:

true if the capability is provided, false else

getReasonerHint

public ReasonerDescriptor getReasonerHint()

Returns the current reasoner hint.

Returns:

the current reasoner hint, may be null;

findReasoner

IReasoner findReasoner(ReasonerDescriptor descriptor)

Finds a reasoner and throws related exceptions.

Parameters:

descriptor - the descriptor of the reasoner to find

Returns:

the reasoner

Throws:

java.lang.IllegalArgumentException - in case of illegal arguments such as null or an unmatching descriptor

findReasoner

public IReasoner findReasoner(java.lang.String name,
                              java.lang.String version)

Returns the first version with given name and version.

Parameters:

name - the name of the reasoner as given in its descriptor

version - the version of the reasoner as given in its descriptor (ignored if null)

Returns:

the first reasoner matching the criteria

Throws:

java.lang.IllegalArgumentException - in case of illegal arguments such as null or an unmatching descriptor

register

public void register(IMessageListener listener)

Registers a message listener.

Parameters:

listener - the listener to register

unregister

public void unregister(IMessageListener listener)

Unregisters a message listener.

Parameters:

listener - the listener to unregister

reasoningSupported

public boolean reasoningSupported()

Checks whether at least one reasoner is present.

Returns:

true if at least one reasoner is present and reasoning can be done, otherwise false

setTimeout

public void setTimeout(int timeout)

Changes the global timeout for reasoning.

Parameters:

timeout - the global timeout in ms, shall be ignored if less negative or null

getTimeout

public int getTimeout()

Returns the global timeout for reasoning.

Returns:

the global timeout in ms, shall be ignored if less negative or null

getPreferredReasoner

public ReasonerDescriptor getPreferredReasoner()

Returns the preferred reasoner descriptor due to internal knowledge about the reasoner implementation status. Currently, we rely on the the reasoner with the maximum number of supported capabilities (currently, the SSE-Reasoner). This method is particularly helpful for repeatable testing.

Returns:

the preferred reasoner (may be null if there is none registered)

See Also:

setReasonerHint(ReasonerDescriptor)

setPreferredReasoner

public ReasonerDescriptor setPreferredReasoner()

Sets the actually preferred reasoner as hint.

Returns:

the preferred reasoner (may be null if there is none registered)

See Also:

getPreferredReasoner(), setReasonerHint(ReasonerDescriptor)

isChainingReasoner

public boolean isChainingReasoner(ReasonerDescriptor descriptor)

Returns whether the reasoner registered for this descriptor is a chaining reasoner.

Parameters:

descriptor - the descriptor

Returns:

true for chaining, false else

createInstance

public IReasonerInstance createInstance(net.ssehub.easy.varModel.confModel.Configuration cfg,
                                        ReasonerConfiguration reasonerConfiguration)

Creates a reasoner instance for repeated reasoning on the same model (no structural changes allowed during two subsequent reasoning runs). Takes the project from the configuration. Corresponding method with project and configuration may become deprecated/disappear in future.

Parameters:

cfg - the configuration as a basis for the evaluation

reasonerConfiguration - the reasoner configuration to be used for reasoning (e.g. taken from the UI, may be null)

Returns:

a reusable reasoner instance, return a DelegatingReasonerInstance on this reasoner to avoid null pointer checking.

See Also:

#createInstance(Project, Configuration, ReasonerConfiguration)

createValue

public ValueCreationResult createValue(net.ssehub.easy.varModel.confModel.Configuration cfg,
                                       net.ssehub.easy.varModel.model.AbstractVariable var,
                                       net.ssehub.easy.varModel.model.datatypes.IDatatype type,
                                       ReasonerConfiguration reasonerConfiguration,
                                       net.ssehub.easy.basics.progress.ProgressObserver observer)

Creates the value for a certain IVML type/variable.

Parameters:

cfg - the configuration to operate on (will not be modified)

var - the variable to create the value for (may be null if type is given, may imply additional constraints, takes precedence over type)

type - the type to create the value for (may be null if var is given)

reasonerConfiguration - the reasoner configuration to be used for reasoning (e.g. taken from the UI, may be null)

observer - an optional progress observer, shall be ProgressObserver.NO_OBSERVER if unused

Returns:

the value creation result