Package net.ssehub.easy.reasoning.core.frontend

Class 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

    • Constructor Detail

      • ReasonerFrontend

        private ReasonerFrontend()
        Singleton constructor for this class.

    • Method Detail

      • installConfigurationInitializer

        private void installConfigurationInitializer()
        Installs the configuration intializer.

      • checkForCapabilitiy

        private static IReasoner checkForCapabilitiy​(IReasoner reasoner,
                                             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

      • getActualReasoner

        private IReasoner getActualReasoner​(Configuration configuration,
                                    java.util.List<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​(Project project,
                                    ReasonerConfiguration reasonerConfiguration,
                                    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​(Configuration cfg,
                             ReasonerConfiguration reasonerConfiguration,
                             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​(Configuration cfg,
                                 ReasonerConfiguration reasonerConfiguration,
                                 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​(Configuration cfg,
                                 java.util.List<Constraint> constraints,
                                 ReasonerConfiguration reasonerConfiguration,
                                 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,
                                       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​(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​(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)

      • 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​(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​(Configuration cfg,
                                       AbstractVariable var,
                                       IDatatype type,
                                       ReasonerConfiguration reasonerConfiguration,
                                       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