Package org.eclipse.epsilon.epl

Class AbstractEplModule

java.lang.Object
org.eclipse.epsilon.common.module.AbstractModuleElement
org.eclipse.epsilon.eol.AbstractModule
org.eclipse.epsilon.eol.EolModule
org.eclipse.epsilon.erl.ErlModule
org.eclipse.epsilon.epl.AbstractEplModule
All Implemented Interfaces:
IModule, ModuleElement, IEolModule, IEplModule, IErlModule
Direct Known Subclasses:
EplModule
public abstract class AbstractEplModule extends ErlModule implements IEplModule
Base implementation of IEplModule allowing for alternative extensions / implementations.
Since:
1.6
Author:
Sina Madani

  • Field Details

    • INFINITE

      public static final int INFINITE
      See Also:

    • patterns

      protected List<Pattern> patterns

    • declaredPatterns

      protected final ArrayList<Pattern> declaredPatterns

    • repeatWhileMatchesFound

      protected boolean repeatWhileMatchesFound

    • maxLoops

      protected int maxLoops

    • patternMatchModelName

      protected String patternMatchModelName

  • Constructor Details

    • AbstractEplModule

      public AbstractEplModule()

    • AbstractEplModule

      public AbstractEplModule(IEplContext context)

  • Method Details

    • getContext

      public IEplContext getContext()
      Specified by:
      getContext in interface IEolModule
      Specified by:
      getContext in interface IErlModule
      Overrides:
      getContext in class ErlModule

    • createLexer

      protected org.antlr.runtime.Lexer createLexer(org.antlr.runtime.ANTLRInputStream inputStream)
      Overrides:
      createLexer in class ErlModule

    • createParser

      public EpsilonParser createParser(org.antlr.runtime.TokenStream tokenStream)
      Overrides:
      createParser in class ErlModule

    • getMainRule

      public String getMainRule()
      Overrides:
      getMainRule in class ErlModule

    • getImportConfiguration

      public HashMap<String,Class<? extends IModule>> getImportConfiguration()
      Overrides:
      getImportConfiguration in class ErlModule

    • adapt

      public ModuleElement adapt(AST cst, ModuleElement parentAst)
      Overrides:
      adapt in class ErlModule

    • build

      public void build(AST cst, IModule module)
      Specified by:
      build in interface ModuleElement
      Overrides:
      build in class ErlModule

    • processRules

      protected Object processRules() throws EolRuntimeException
      Description copied from class: ErlModule
      Main rule processing logic. Non-abstract for compatibility.
      Overrides:
      processRules in class ErlModule
      Returns:
      The result of executing this module.
      Throws:
      EolRuntimeException

    • getDeclaredPatterns

      public List<Pattern> getDeclaredPatterns()
      Specified by:
      getDeclaredPatterns in interface IEplModule

    • getPatterns

      public List<Pattern> getPatterns()
      Specified by:
      getPatterns in interface IEplModule

    • getMaxLoops

      public int getMaxLoops()
      Specified by:
      getMaxLoops in interface IEplModule

    • setMaxLoops

      public void setMaxLoops(int maxLoops)
      Specified by:
      setMaxLoops in interface IEplModule

    • isRepeatWhileMatches

      public boolean isRepeatWhileMatches()
      Specified by:
      isRepeatWhileMatches in interface IEplModule

    • setRepeatWhileMatches

      public void setRepeatWhileMatches(boolean repeatWhileMatches)
      Specified by:
      setRepeatWhileMatches in interface IEplModule

    • matchPatterns

      public final PatternMatchModel matchPatterns() throws EolRuntimeException
      Specified by:
      matchPatterns in interface IEplModule
      Throws:
      EolRuntimeException

    • match

      public Collection<PatternMatch> match(Pattern pattern) throws EolRuntimeException
      This method provides the main high-level execution logic for EPL. The idea is that for each role in the pattern, appropriate bindings are made to the role and executed. Then the match block (and subsequently onMatch) is executed for the role and a PatternMatch is created where applicable.
      In essence, this method can be thought of as the executor of all roles in the pattern, and therefore acts as a bridge between the high-level methods (e.g. matchPatterns(int, PatternMatchModel)) and the low-level ones (e.g. getRoleInstances(Role, String)).
      Implementation-wise, this method delegates the main execution logic to matchCombination(Collection, Pattern), and so the sole responsibility of this method is to loop through the combinations returned by getCandidates(Pattern) and collect all the results. Subclasses may override this method to alter the type of collection returned and/or alter the looping mechanism.
      Specified by:
      match in interface IEplModule
      Throws:
      EolRuntimeException

    • matchCombination

      protected final Optional<PatternMatch> matchCombination(Collection<? extends Iterable<?>> combination, Pattern pattern) throws EolRuntimeException
      Executes the match, onmatch and/or nomatch blocks.
      Parameters:
      combination - The values to use for role bindings.
      pattern -
      Returns:
      A PatternMatch if the criteria was met, empty otherwise.
      Throws:
      EolRuntimeException

    • createModel

      protected PatternMatchModel createModel() throws EolRuntimeException
      PatternMatchModel factory method.
      Throws:
      EolRuntimeException

    • preMatch

      protected void preMatch(PatternMatchModel model) throws EolRuntimeException
      Pre-processes the model.
      Throws:
      EolRuntimeException

    • matchPatterns

      protected Set<PatternMatch> matchPatterns(int level, PatternMatchModel model) throws EolRuntimeException
      Adds all matches returned by IEplModule#match() to the match model for all patterns at the specified level.
      Returns:
      The set of pattern matches added to the model.
      Throws:
      EolRuntimeException

    • postProcessMatches

      protected final void postProcessMatches(int level, Collection<PatternMatch> matches) throws EolRuntimeException
      Executes the do block for all matched patterns at the specified level. To control the execution of the block itself, subclasses can override the executeDoBlock(ExecutableBlock, Map) method.
      Throws:
      EolRuntimeException

    • executeDoBlock

      protected Object executeDoBlock(ExecutableBlock<?> doBlock, Map<String,Object> roleBindings) throws EolRuntimeException
      Executes the do block with the specified variables.
      Parameters:
      doBlock - The block to execute.
      roleBindings - The effective collection of variables.
      Returns:
      The result of the block, usually null.
      Throws:
      EolRuntimeException

    • getMatchResult

      protected final boolean getMatchResult(Pattern pattern) throws EolRuntimeException
      Gets the result of the match block for the specified pattern.
      Parameters:
      pattern - the pattern being executed
      context - the context
      Returns:
      the result of executing the match block or true if the pattern does not define a match block.
      Throws:
      EolRuntimeException - if the result is not a boolean.

    • createPatternMatch

      protected PatternMatch createPatternMatch(Pattern pattern, Collection<? extends Iterable<?>> combination)
      Converts all roles of the pattern into a PatternMatch with the specified bindings. Note that the size of combinations must be equal to the number of roles in the pattern. The inner (nested) iterable of combinations are the source bindings for each role name.
      See Also:
      • #flatMapRoleBindings(Pattern, Iterable)

    • flatMapRoleBindings

      protected static final Collection<Variable> flatMapRoleBindings(Collection<Role> roles, Collection<? extends Iterable<?>> combination)
      This method simply flatmaps the results of calling getVariables(Iterable, Role) for each role in the pattern. It will iterate over the larger of pattern.getRoles() and combination collections first.
      Parameters:
      roles - The roles of a pattern.
      combination - The instances for each binding. Note that the inner iterable's size must be equal to the number of names in the role. However the outer size (that is, combination.size()) need not necessarily be equal to the number of roles in the pattern.
      Returns:
      A flattened view of the Collection of Collection of Variables.

    • getVariables

      protected static Collection<Variable> getVariables(Iterable<?> bindings, Role role)
      Binds role names to the objects returned by the bindings iterator.
      Parameters:
      bindings - The elements to map to each role name. Note that the number of objects returned by the iterator must be equal to the number of role names.
      role -
      Returns:
      The variables, effectively a Collection<Map.Entry<String, ?>> where the entry is the role name and value is the model element bound to it.

    • putRoleBindingsIntoFrame

      protected static final int putRoleBindingsIntoFrame(Collection<Role> roles, Collection<? extends Iterable<?>> combination, Frame frame)
      Puts the result of #flatMapRoleBindings(Pattern, Collection) into the frame.
      Parameters:
      roles -
      combinations -
      frame -
      Returns:
      The number of variables inserted into the frame.

    • isValidCombination

      protected boolean isValidCombination(Pattern pattern, List<? extends Iterable<?>> combination) throws EolRuntimeException
      Validates whether the given combination matches the constraints imposed by the pattern.
      Parameters:
      pattern -
      combination -
      Returns:
      Throws:
      EolRuntimeException

    • getCandidates

      protected abstract Iterator<? extends Collection<? extends Iterable<?>>> getCandidates(Pattern pattern) throws EolRuntimeException
      The dimensions of the returned nested Iterables are as follows:

      Outer: The number of roles in the pattern (i.e. pattern.getRoles().size())

      Mid: The number of instances as returned by RoleExecutor#getRoleInstances(Role, String) multiplied by the number of names for that role (i.e. getRoleInstances(role).size()*role.getNames().size()).

      Inner: The number of elements which satisfy the guard and domain of the role, holding the value of previous role bindings and variables constant. As such, the dimensions of this inner-most Iterable can vary throughout execution if the role has dependencies on values computed in prior roles.
      Parameters:
      pattern -
      Returns:
      All combinations of model element instances conforming to the constraints imposed by the pattern's roles. Note that in most cases this will not be a Collection, but a generator (lazy Iterator) wrapped into an Iterable for convenience.
      Throws:
      EolRuntimeException

    • getRoleInstances

      protected final Collection<?> getRoleInstances(Role role, String roleName) throws EolRuntimeException
      Executes the role, returning applicable model elements which satisfy the conditions specified in the role. Since roles may depend on other roles, which in turn depend on the combination of elements currently bound to those roles, the implementation of this method is non-trivial.
      This method structures the execution of a role and for consistency, it cannot be overriden. Subclasses should override the #negativeGuard(ExecutableBlock, Collection) and/or #filterElements(ExecutableBlock, Collection) methods as these involve executing guard blocks for each element. If even greater control is desired (e.g. to change the return type of the collection), subclasses can override the intermediate methods, which are:
      Parameters:
      role -
      roleName - The name to which instances will be bound when executing the guard block. This will always come from role.getNames()
      Returns:
      All objects satisfying the constraints of the role.
      Throws:
      EolRuntimeException

    • wrapBasicRoleInstances

      protected abstract Collection<?> wrapBasicRoleInstances(Role role, String roleName, AbstractEplModule.LazyBasicRoleInstancesInitializer initializer) throws EolRuntimeException
      Wraps the result of preprocessRoleInstances(Role, String) into the specified collection.
      Parameters:
      role -
      roleName -
      initializer - Method reference to preprocessRoleInstances(Role, String).
      Returns:
      The result of AbstractEplModule.LazyBasicRoleInstancesInitializer.get(Role, String); either directly or wrapped into a custom collection.
      Throws:
      EolRuntimeException

    • wrapAdvancedRoleInstances

      protected abstract Collection<?> wrapAdvancedRoleInstances(Role role, String roleName, Collection<?> currentInstances, AbstractEplModule.LazyAdvancedRoleInstancesInitializer initializer) throws EolRuntimeException
      Parameters:
      role -
      roleName -
      currentInstances - The values returned from wrapBasicRoleInstances(Role, String, LazyBasicRoleInstancesInitializer).
      initializer - Method reference to getNegativeRoleInstances(Role, String, Collection) or getAllRoleInstances(Role, String, Collection).
      Returns:
      The result of LazyAdvancedRoleInstancesInitializer#initialize(Role, String); either directly or wrapped into a custom collection.
      Throws:
      EolRuntimeException

    • negativeGuard

      protected boolean negativeGuard(ExecutableBlock<Boolean> guard, String roleName, Collection<?> currentInstances) throws EolRuntimeException
      Executes the guard block when called by getNegativeRoleInstances(Role, String, Collection)
      Parameters:
      guard -
      currentInstances - The model elements of the negative role.
      Returns:
      Whether any of the elements in currentInstances satisfy the guard.
      Throws:
      EolRuntimeException

    • filterElements

      protected Collection<?> filterElements(ExecutableBlock<Boolean> guard, String roleName, Collection<?> currentInstances) throws EolRuntimeException
      Executes the guard block when called by getAllRoleInstances(Role, String, Collection)
      Parameters:
      guard -
      currentInstances - The model elements of the role.
      Returns:
      The subset of model elements satisfying the guard.
      Throws:
      EolRuntimeException