Package net.ssehub.easy.varModel.cstEvaluation

Class EvaluationVisitor

java.lang.Object
net.ssehub.easy.varModel.cstEvaluation.EvaluationVisitor
All Implemented Interfaces:
IConstraintTreeVisitor, IConstraintEvaluator
public class EvaluationVisitor extends Object implements IConstraintTreeVisitor, IConstraintEvaluator
Evaluation visitor for IVML expressions. Usage:
  1. Single use: Call EvaluationVisitor(IConfiguration, IAssignmentState, boolean, IValueChangeListener), visit(ConstraintSyntaxTree), call getResult() and finally clear().
  2. Reuse: Call EvaluationVisitor(). Before visiting, call init(IConfiguration, IAssignmentState, boolean, IValueChangeListener), visit(ConstraintSyntaxTree), call getResult() and then clear(). Now you can go on with init(IConfiguration, IAssignmentState, boolean, IValueChangeListener) etc.
  3. Do not forget to set the dispatch scope to the project which is currently being evaluated.
Please note that you may also let the constraint accept the visitor directly, but then the evaluation will fail if static compound accesses occur. Please use visit(ConstraintSyntaxTree) instead.
Please do not forget to call clear()! clearResult() allows to reuse a visitor including the settings made in init(IConfiguration, IAssignmentState, boolean, IValueChangeListener).
Personally, I would handle evaluation problems with exceptions, but the visitor interface and the classes to be visited are not defined to support this adequately. An IEvaluationInterceptor may be given to collect/influence values before setting them, in particular in case of default values.
Author:
Holger Eichelberger

  • Field Details

  • Constructor Details

    • EvaluationVisitor

      public EvaluationVisitor()
      Creates an evaluation visitor.

    • EvaluationVisitor

      public EvaluationVisitor(IConfiguration config, IAssignmentState assignmentState, boolean assignmentsOnly, IValueChangeListener listener)
      Creates an evaluation visitor.
      Parameters:
      config - the configuration to take already evaluated values from
      assignmentState - the state for the assignments (may be null if no assignment shall take place)
      assignmentsOnly - if true process only assignments, else process all constraints
      listener - a listener to notify some external mechanism about a changed variable (may be null)

  • Method Details

    • init

      public void init(IConfiguration config, IAssignmentState assignmentState, boolean assignmentsOnly, IValueChangeListener listener)
      Clears the visitor for reuse.
      Parameters:
      config - the configuration to take already evaluated values from
      assignmentState - the state for the assignments (may be null if no assignment shall take place)
      assignmentsOnly - if true process only assignments, else process all constraints
      listener - a listener to notify some external mechanism about a changed variable (may be null)

    • setAssignmentState

      public void setAssignmentState(IAssignmentState assignmentState)
      Allow changing the assignment state to do an init(IConfiguration, IAssignmentState, boolean, IValueChangeListener), a repeated evaluation with changing assignment state and finally a clear() or clearResult().
      Parameters:
      assignmentState - the state for the assignments (may be null if no assignment shall take place)

    • setResolutionListener

      public void setResolutionListener(IResolutionListener listener)
      Defines the current (optional) resolution listener.
      Parameters:
      listener - the listener (may be null to indicate that no listener is required)

    • setValueChangeListener

      public void setValueChangeListener(IValueChangeListener listener)
      Defines the current (optional) value change listener listener.
      Parameters:
      listener - the listener (may be null to indicate that no listener is required)

    • addMapping

      void addMapping(AbstractVariable decl, IDecisionVariable var)
      Adds an explicit mapping of a declaration to a decision variable taking precedence over the configuration. This is in particular required for evaluating freeze-but.
      Parameters:
      decl - the declaration
      var - the variable

    • removeMapping

      void removeMapping(AbstractVariable decl)
      Removes an explicit mapping of a declaration to a decision variable as counterpart for addMessage(Message). This is in particular required for evaluating freeze-but.
      Parameters:
      decl - the declaration

    • setDispatchScope

      public Project setDispatchScope(Project scope)
      Defines the top-level search scope for dynamic dispatch of custom operations.
      Parameters:
      scope - the scope (may be null to disable dynamic dispatch)
      Returns:
      the scope before calling this operation

    • setSelfValue

      public void setSelfValue(CompoundValue selfValue)
      Changes the value of "self" for the current compound in case that constraint evaluation does not happen via visit(ConstraintSyntaxTree). May be overwritten by visit(ConstraintSyntaxTree).
      Parameters:
      selfValue - the self value, may be null if evaluation happens not in a compound

    • clear

      public void clear()
      Clears the visitor for reuse (including the dispatch scope and the context).
      See Also:

    • clearIntermediary

      public void clearIntermediary()
      Clears intermediary state information including result, assignment state, messages, warnings, failed and selfVars. Call at least setAssignmentState(IAssignmentState) to reuse this instance.

    • clearResult

      public void clearResult()
      Clears the result. Does not clear the context stack, which may contain frames in case of evaluation problems.

    • getResult

      public Value getResult()
      Description copied from interface: IConstraintEvaluator
      Returns the evaluation result.
      Specified by:
      getResult in interface IConstraintEvaluator
      Returns:
      may be null in case of an expression that cannot be evaluated (shall lead to an exception)

    • getResultVariable

      public IDecisionVariable getResultVariable()
      Returns the result variable.
      Returns:
      may be null in case of an expression that cannot be evaluated (shall lead to an exception)

    • getResultAccessor

      protected EvaluationAccessor getResultAccessor(boolean nullify)
      Just for internal purposes of derived classes - get the result accessor. If you use this method, you are anyway responsible for cleaning up the result properly.
      Parameters:
      nullify - set result to null and caller takes over full responsibility for releasing, false leave responsibility in this part
      Returns:
      the result accessor

    • setResultAcessor

      protected void setResultAcessor(EvaluationAccessor result)
      Defines the result accessor and overrides an existing accessor. Please use with care. This part takes over the responsibility for releasing the accessor.
      Parameters:
      result - the new result accessor (may be null for none)

    • constraintFulfilled

      public static boolean constraintFulfilled(Object result)
      Returns whether the result of a constraint evaluation indicates that the evaluated constraint was fulfilled.
      Parameters:
      result - the evaluation result
      Returns:
      true if the constraint is fulfilled, false else

    • constraintFailed

      public static boolean constraintFailed(Object result)
      Returns whether the result of a constraint evaluation indicates that the evaluated constraint failed.
      Parameters:
      result - the evaluation result
      Returns:
      true if the constraint failed, false else

    • constraintUndefined

      public static boolean constraintUndefined(Object result)
      Returns whether the result of a constraint evaluation indicates that (at least one part of) the constraint was undefined.
      Parameters:
      result - the evaluation result
      Returns:
      true if (at least one part of) the constraint was undefined, false else

    • constraintFulfilled

      public boolean constraintFulfilled()
      Description copied from interface: IConstraintEvaluator
      Returns whether the constraint evaluation indicates that the evaluated constraint was fulfilled.
      Specified by:
      constraintFulfilled in interface IConstraintEvaluator
      Returns:
      true if the constraint is fulfilled, false else

    • constraintFailed

      public boolean constraintFailed()
      Description copied from interface: IConstraintEvaluator
      Returns whether the constraint evaluation indicates that the evaluated constraint failed. For instance, the following should fail: 
      
 a = true;
 b = false;
 
 !a or b
      Specified by:
      constraintFailed in interface IConstraintEvaluator
      Returns:
      true if the constraint failed, false else

    • constraintUndefined

      public boolean constraintUndefined()
      Description copied from interface: IConstraintEvaluator
      Returns whether the constraint evaluation indicates that (at least one part of) the constraint was undefined.
      Specified by:
      constraintUndefined in interface IConstraintEvaluator
      Returns:
      true if (at least one part of) the constraint was undefined, false else

    • constraintIsAWarning

      public boolean constraintIsAWarning()
      Description copied from interface: IConstraintEvaluator
      Returns whether the constraint was internally evaluated to false but finally leads to a successful execution and shall lead to a warning to the user.
      Specified by:
      constraintIsAWarning in interface IConstraintEvaluator
      Returns:
      true if the constraint shall be issued as a warning, false else.

    • getFailedExpression

      public ConstraintSyntaxTree[] getFailedExpression()
      Returns the innermost failed expression(s).
      Returns:
      null if there were no failed expressions, the (innermost) failed expressions else (currently at maximum one)

    • addMessage

      private void addMessage(EvaluationVisitor.Message message)
      Adds a message.
      Parameters:
      message - the message to be added

    • error

      private void error(String text, int code)
      Adds an error message.
      Parameters:
      text - the text of the error message
      code - the message code

    • notImplementedError

      private void notImplementedError(String subject)
      Adds a not implemented error message.
      Parameters:
      subject - the subject that is not implemented

    • exception

      private void exception(Throwable th)
      Adds a throwable as error message.
      Parameters:
      th - the throwable

    • getMessageCount

      public int getMessageCount()
      Description copied from interface: IConstraintEvaluator
      Returns the number of messages.
      Specified by:
      getMessageCount in interface IConstraintEvaluator
      Returns:
      the number of messages

    • getMessage

      public EvaluationVisitor.Message getMessage(int index)
      Description copied from interface: IConstraintEvaluator
      Returns the specified evaluation message.
      Specified by:
      getMessage in interface IConstraintEvaluator
      Parameters:
      index - the message to return
      Returns:
      the specified message

    • visit

      public ConstraintSyntaxTree visit(ConstraintSyntaxTree cst)
      Visits a constraint syntax tree. This method considers partial expressions with static access and wraps the entire expression into an all-quantified constraint. "Free" variables are bound by all-quantors constructed for individual compound types. Multiple slots for one compound are then bound by variable let expressions. As a result, the entire constraint is bound against the all-instance sets of the individual types and can be handled as all other constraints by the EvaluationVisitor.
      Parameters:
      cst - the constraint to be evaluated
      Returns:
      the rewritten constraint if needed, cst else

    • bindFreeVarsByQuantors

      private ConstraintSyntaxTree bindFreeVarsByQuantors(ConstraintSyntaxTree cst, Map<IDatatype,List<AbstractVariable>> quantorGroups)
      Binds the free variables by one quantor per quantor group.
      Parameters:
      cst - the constraint to be quantorized/bound
      quantorGroups - the quantor groups
      Returns:
      the resulting rewritten constraint (may be null if errors occcurred)

    • visitConstantValue

      public void visitConstantValue(ConstantValue value)
      Description copied from interface: IConstraintTreeVisitor
      Visits a constant value.
      Specified by:
      visitConstantValue in interface IConstraintTreeVisitor
      Parameters:
      value - the value which should be visited

    • visitVariable

      public void visitVariable(Variable variable)
      Description copied from interface: IConstraintTreeVisitor
      Visits a variable.
      Specified by:
      visitVariable in interface IConstraintTreeVisitor
      Parameters:
      variable - the variable which should be visited

    • visitParenthesis

      public void visitParenthesis(Parenthesis parenthesis)
      Description copied from interface: IConstraintTreeVisitor
      Visits a parenthesis.
      Specified by:
      visitParenthesis in interface IConstraintTreeVisitor
      Parameters:
      parenthesis - the parenthesis which should be visited

    • visitDeferInitExpression

      public void visitDeferInitExpression(DeferInitExpression expression)
      Description copied from interface: IConstraintTreeVisitor
      Visits a default init expression.
      Specified by:
      visitDeferInitExpression in interface IConstraintTreeVisitor
      Parameters:
      expression - the expression

    • visitComment

      public void visitComment(Comment comment)
      Description copied from interface: IConstraintTreeVisitor
      Visits a comment.
      Specified by:
      visitComment in interface IConstraintTreeVisitor
      Parameters:
      comment - the comment node which should be visited

    • evaluateCustomOperation

      private void evaluateCustomOperation(CustomOperation operation, EvaluationAccessor operand, EvaluationAccessor[] args)
      Evaluates the given custom operation.
      Parameters:
      operation - the operation to be evaluated
      operand - the call operand (may be null; if not, added to parameters)
      args - the call arguments

    • handleBinaryBoolean

      private boolean handleBinaryBoolean(EvaluationAccessor operand, OCLFeatureCall call)
      Handles an BooleanType.AND, BooleanType.OR or BooleanType.XOR operation. Should evaluate special situations like undef OR true to true. Dynamically changes evaluation sequence depending on containsIsDefined(ConstraintSyntaxTree).
      Parameters:
      operand - The operand of the OR operation. The operand should already been visited.
      call - the call representing the OR operation
      Returns:
      true the operation was evaluated successfully, false otherwise.

    • getAccessor

      private EvaluationAccessor getAccessor(EvaluationAccessor accessor, ConstraintSyntaxTree expression)
      Returns an evaluation accessor for expression if accessor is not already determined.
      Parameters:
      accessor - the accessor
      expression - the expression
      Returns:
      the accessor, may be accessor, may be a new accessor, may be null. Must be released if not null

    • evaluateOclFeatureCall

      private boolean evaluateOclFeatureCall(OCLFeatureCall call)
      Returns whether an OCL feature call shall be evaluated.
      Parameters:
      call - the specific call to consider
      Returns:
      true if the call shall be evaluated, false else

    • setAllowPropagation

      private boolean setAllowPropagation(Operation op, boolean allow)
      Encapsulates a null context (some of the model test cases).
      Parameters:
      op - the operation to consider
      allow - the new state of the allow flag
      Returns:
      the old state of the allow flag

    • containsIsDefined

      private boolean containsIsDefined(ConstraintSyntaxTree constraint)
      Returns whether constraint somewhere contains/calls an isDefined operation. Alternative would be constraint rewriting during parsing.
      Parameters:
      constraint - the constraint
      Returns:
      true if isDefined is somewhere used, false else

    • visitOclFeatureCall

      public void visitOclFeatureCall(OCLFeatureCall call)
      Description copied from interface: IConstraintTreeVisitor
      Visits an OCL feature call.
      Specified by:
      visitOclFeatureCall in interface IConstraintTreeVisitor
      Parameters:
      call - the feature call which should be visited

    • evaluateArguments

      private boolean evaluateArguments(OCLFeatureCall call, Operation op, EvaluationAccessor operand, EvaluationAccessor[] args)
      Evaluates the arguments.
      Parameters:
      call - the call
      op - the resolved operation
      operand - the operand
      args - the arguments (empty, size of number of parameters, modified as side effect)
      Returns:
      true for successful, false else

    • recordIfFailed

      private void recordIfFailed(ConstraintSyntaxTree cst)
      Records a constraint syntax tree if it failed.
      Parameters:
      cst - the syntax tree to record

    • dynamicDispatch

      private CustomOperation dynamicDispatch(CustomOperation operation, EvaluationAccessor[] args)
      Performs a dynamic dispatch of operation according to the given actual arguments in args, i.e., this method searches and returns a method that fits better to the actual arguments then the statically bound operation.
      Parameters:
      operation - the operation to be dispatched
      args - the actual arguments
      Returns:
      the best fitting operation

    • visitLet

      public void visitLet(Let let)
      Description copied from interface: IConstraintTreeVisitor
      Visits a let expression.
      Specified by:
      visitLet in interface IConstraintTreeVisitor
      Parameters:
      let - the let expression which should be visited

    • disposeLocalVariable

      void disposeLocalVariable(LocalDecisionVariable var)
      Notifies the resolution listener about disposing a local variable.
      Parameters:
      var - the variable

    • disposeLocalVariables

      void disposeLocalVariables(LocalDecisionVariable[] vars)
      Notifies the resolution listener about disposing several local variables.
      Parameters:
      vars - the variables

    • addLocalVariable

      private LocalDecisionVariable addLocalVariable(LocalConfiguration cfg, DecisionVariableDeclaration decl, ConstraintSyntaxTree initEx, boolean notify)
      Adds a new local decision variable based on decl to cfg.
      Parameters:
      cfg - the local configuration to add the new variable
      decl - the variable declaration
      initEx - the explicitly given initialization expression, may be null then this method considers the default value of decl
      notify - notify the resolution listener about the creation of the new variable, unregistering must follow
      Returns:
      the created local variable

    • visitIfThen

      public void visitIfThen(IfThen ifThen)
      Description copied from interface: IConstraintTreeVisitor
      Visits an if-then-else expression.
      Specified by:
      visitIfThen in interface IConstraintTreeVisitor
      Parameters:
      ifThen - the if-then-else expression which should be visited

    • visitContainerOperationCall

      public void visitContainerOperationCall(ContainerOperationCall call)
      Description copied from interface: IConstraintTreeVisitor
      Visits a container operation call (e.g. quantors, iterators).
      Specified by:
      visitContainerOperationCall in interface IConstraintTreeVisitor
      Parameters:
      call - the container operation call

    • executeContainerIteration

      private boolean executeContainerIteration(ContainerOperationCall call, LocalDecisionVariable[] declarators, int iterCount, VariableAccessor resultVar, IIteratorEvaluator evaluator)
      Executes the container iteration.
      Parameters:
      call - the container operation call to be executed
      declarators - all declarators of the call in terms of decision variables
      iterCount - the number of iterators within the declarators
      resultVar - the result variable to be modified as a side effect during the iteration (result aggregation)
      evaluator - the evaluator corresponding to call (may be null in case of an apply operation)
      Returns:
      true if successful, false if unevaluated

    • containerException

      private boolean containerException(Throwable throwable)
      Just a wrapper for container exceptions constantly returning false. Calls exception(Throwable).
      Parameters:
      throwable - the exception
      Returns:
      false

    • isFreezeVariable

      private boolean isFreezeVariable(ConstraintSyntaxTree cst)
      Returns whether cst is a freeze variable.
      Parameters:
      cst - the cst to check
      Returns:
      true if cst contains a freeze variable, false else

    • visitCompoundAccess

      public void visitCompoundAccess(CompoundAccess access)
      Description copied from interface: IConstraintTreeVisitor
      Visits a compound access node.
      Specified by:
      visitCompoundAccess in interface IConstraintTreeVisitor
      Parameters:
      access - the compound access node

    • visitUnresolvedExpression

      public void visitUnresolvedExpression(UnresolvedExpression expression)
      Description copied from interface: IConstraintTreeVisitor
      Visits an unresolved expression. Please note that an unresolved expression may represent a leaf as well as an inner tree node. Typically, visitors shall continue visiting transparently at UnresolvedExpression.getActualExpression().
      Specified by:
      visitUnresolvedExpression in interface IConstraintTreeVisitor
      Parameters:
      expression - the expression

    • createInits

      private List<EvaluationVisitor.CompoundSlotInit> createInits(CompoundInitializer initializer)

    • pull

      private EvaluationVisitor.CompoundSlotInit pull(List<EvaluationVisitor.CompoundSlotInit> slotInits)

    • visitCompoundInitializer

      public void visitCompoundInitializer(CompoundInitializer initializer)
      Description copied from interface: IConstraintTreeVisitor
      Visits a compound initializer.
      Specified by:
      visitCompoundInitializer in interface IConstraintTreeVisitor
      Parameters:
      initializer - the compound initializer node

    • visitContainerInitializer

      public void visitContainerInitializer(ContainerInitializer initializer)
      Description copied from interface: IConstraintTreeVisitor
      Visits a container initializer.
      Specified by:
      visitContainerInitializer in interface IConstraintTreeVisitor
      Parameters:
      initializer - the container initializer node

    • visitSelf

      public void visitSelf(Self self)
      Description copied from interface: IConstraintTreeVisitor
      Visits self.
      Specified by:
      visitSelf in interface IConstraintTreeVisitor
      Parameters:
      self - the self object to visit

    • getOperationEvaluator

      protected IOperationEvaluator getOperationEvaluator(Operation operation)
      Returns the operation evaluator for the given operation. This method is intended to be overridden in case that other operations than the default ones from the EvaluatorRegistry shall be used.
      Parameters:
      operation - the operation to return the evaluator for
      Returns:
      the operation evaluator (or null if none is known)

    • getIteratorEvaluator

      protected IIteratorEvaluator getIteratorEvaluator(Operation operation)
      Returns the iterator evaluator for the given operation. This method is intended to be overridden in case that other operations than the default ones from the EvaluatorRegistry shall be used.
      Parameters:
      operation - the operation to return the evaluator for
      Returns:
      the iterator evaluator (or null if none is known)

    • getTargetState

      protected IAssignmentState getTargetState(IDecisionVariable var)
      Returns the target state for a variable which is actually being assigned. This method is intended to be overriden if state conflicts shall be checked before assignment.
      Parameters:
      var - variable
      Returns:
      the target state for the variable, may be null if assignment is not permitted

    • getTargetState

      protected IAssignmentState getTargetState()
      Returns the target assignment state assigned to this visitor.
      Returns:
      the target state

    • visitAnnotationVariable

      public void visitAnnotationVariable(AttributeVariable variable)
      Description copied from interface: IConstraintTreeVisitor
      Visits a AttributeVariable.
      Specified by:
      visitAnnotationVariable in interface IConstraintTreeVisitor
      Parameters:
      variable - the attribute variable which should be visited

    • visitBlockExpression

      public void visitBlockExpression(BlockExpression block)
      Description copied from interface: IConstraintTreeVisitor
      Visits the block.
      Specified by:
      visitBlockExpression in interface IConstraintTreeVisitor
      Parameters:
      block - the block to be visited

    • visitMultiAndExpression

      public void visitMultiAndExpression(MultiAndExpression expression)
      Description copied from interface: IConstraintTreeVisitor
      Visits a multi-and expression.
      Specified by:
      visitMultiAndExpression in interface IConstraintTreeVisitor
      Parameters:
      expression - the expression to be visited