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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static interface	AbstractEplModule.LazyAdvancedRoleInstancesInitializer
protected static interface	AbstractEplModule.LazyBasicRoleInstancesInitializer

Field Summary

Fields

Modifier and Type	Field	Description
protected ArrayList<Pattern>	declaredPatterns
static int	INFINITE
protected int	maxLoops
protected String	patternMatchModelName
protected List<Pattern>	patterns
protected boolean	repeatWhileMatchesFound

Fields inherited from class org.eclipse.epsilon.erl.ErlModule

declaredPost, declaredPre, post, pre

Fields inherited from class org.eclipse.epsilon.eol.EolModule

context, declaredModelDeclarations, declaredOperations, imports, main, modelDeclarations, operations, postOperationStatements

Fields inherited from class org.eclipse.epsilon.eol.AbstractModule

parseProblems, parser, sourceFile, sourceUri

Fields inherited from class org.eclipse.epsilon.common.module.AbstractModuleElement

children, comments, data, module, region, uri

Constructor Summary

Constructors

Constructor	Description
AbstractEplModule()
AbstractEplModule(IEplContext context)

Method Summary

Modifier and Type	Method	Description
ModuleElement	adapt(AST cst, ModuleElement parentAst)
void	build(AST cst, IModule module)
protected org.antlr.runtime.Lexer	createLexer(org.antlr.runtime.ANTLRInputStream inputStream)
protected PatternMatchModel	createModel()	PatternMatchModel factory method.
EpsilonParser	createParser(org.antlr.runtime.TokenStream tokenStream)
protected PatternMatch	createPatternMatch(Pattern pattern, Collection<? extends Iterable<?>> combination)	Converts all roles of the pattern into a PatternMatch with the specified bindings.
protected Object	executeDoBlock(ExecutableBlock<?> doBlock, Map<String,Object> roleBindings)	Executes the do block with the specified variables.
protected Collection<?>	filterElements(ExecutableBlock<Boolean> guard, String roleName, Collection<?> currentInstances)	Executes the guard block when called by getAllRoleInstances(Role, String, Collection)
protected static 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.
protected abstract Iterator<? extends Collection<? extends Iterable<?>>>	getCandidates(Pattern pattern)	The dimensions of the returned nested Iterables are as follows: Outer: The number of roles in the pattern (i.e.
IEplContext	getContext()
List<Pattern>	getDeclaredPatterns()
HashMap<String,Class<?>>	getImportConfiguration()
String	getMainRule()
protected boolean	getMatchResult(Pattern pattern)	Gets the result of the match block for the specified pattern.
int	getMaxLoops()
List<Pattern>	getPatterns()
protected Collection<?>	getRoleInstances(Role role, String roleName)	Executes the role, returning applicable model elements which satisfy the conditions specified in the role.
protected static Collection<Variable>	getVariables(Iterable<?> bindings, Role role)	Binds role names to the objects returned by the bindings iterator.
boolean	isRepeatWhileMatches()
protected boolean	isValidCombination(Pattern pattern, List<? extends Iterable<?>> combination)	Validates whether the given combination matches the constraints imposed by the pattern.
Collection<PatternMatch>	match(Pattern pattern)	This method provides the main high-level execution logic for EPL.
protected Optional<PatternMatch>	matchCombination(Collection<? extends Iterable<?>> combination, Pattern pattern)	Executes the match, onmatch and/or nomatch blocks.
PatternMatchModel	matchPatterns()
protected Set<PatternMatch>	matchPatterns(int level, PatternMatchModel model)	Adds all matches returned by IEplModule#match() to the match model for all patterns at the specified level.
protected boolean	negativeGuard(ExecutableBlock<Boolean> guard, String roleName, Collection<?> currentInstances)	Executes the guard block when called by getNegativeRoleInstances(Role, String, Collection)
protected void	postProcessMatches(int level, Collection<PatternMatch> matches)	Executes the do block for all matched patterns at the specified level.
protected void	preMatch(PatternMatchModel model)	Pre-processes the model.
protected Object	processRules()	Main rule processing logic.
protected static int	putRoleBindingsIntoFrame(Collection<Role> roles, Collection<? extends Iterable<?>> combination, Frame frame)	Puts the result of #flatMapRoleBindings(Pattern, Collection) into the frame.
void	setMaxLoops(int maxLoops)
void	setRepeatWhileMatches(boolean repeatWhileMatches)
protected abstract Collection<?>	wrapAdvancedRoleInstances(Role role, String roleName, Collection<?> currentInstances, AbstractEplModule.LazyAdvancedRoleInstancesInitializer initializer)
protected abstract Collection<?>	wrapBasicRoleInstances(Role role, String roleName, AbstractEplModule.LazyBasicRoleInstancesInitializer initializer)	Wraps the result of preprocessRoleInstances(Role, String) into the specified collection.

Methods inherited from class org.eclipse.epsilon.erl.ErlModule

calculateSuperRules, execute, execute, executeImpl, getDeclaredPost, getDeclaredPre, getPost, getPre, postExecution, prepareExecution

Methods inherited from class org.eclipse.epsilon.eol.EolModule

checkImports, clearCache, execute, getDeclaredModelDeclarations, getDeclaredOperations, getImports, getImportsByExtension, getMain, getModelDeclarations, getOperations, getParentModule, getPostOperationStatements, prepareContext, setContext, setMain, setParentModule, toString

Methods inherited from class org.eclipse.epsilon.eol.AbstractModule

assignAnnotations, assignComment, assignComments, createAst, extractComments, getParseProblems, getSourceFile, getSourceUri, invokeMainRule, parse, parse

Methods inherited from class org.eclipse.epsilon.common.module.AbstractModuleElement

equals, getChildren, getComments, getData, getDebugInfo, getFile, getModule, getParent, getRegion, getUri, hashCode, setModule, setParent, setRegion, setUri

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.eclipse.epsilon.eol.IEolModule

configure, execute, getConfigurationProperties, getDeclaredModelDeclarations, getDeclaredOperations, getImports, getMain, getModelDeclarations, getOperations, getParentModule, getParseProblems, getPostOperationStatements, parse, setContext, setParentModule

Methods inherited from interface org.eclipse.epsilon.epl.IEplModule

getMaximumLevel

Methods inherited from interface org.eclipse.epsilon.erl.IErlModule

getDeclaredPost, getDeclaredPre, getPost, getPre

Methods inherited from interface org.eclipse.epsilon.common.module.IModule

createAst, getSourceUri, parse, parse, parse, parse, parse

Methods inherited from interface org.eclipse.epsilon.common.module.ModuleElement

getChildren, getComments, getData, getFile, getModule, getParent, getRegion, getUri, setModule, setParent, setRegion, setUri

Field Detail

INFINITE

public static final int INFINITE

See Also:

Constant Field Values

patterns

protected List<Pattern> patterns

declaredPatterns

protected final ArrayList<Pattern> declaredPatterns

repeatWhileMatchesFound

protected boolean repeatWhileMatchesFound

maxLoops

protected int maxLoops

patternMatchModelName

protected String patternMatchModelName

Constructor Detail

AbstractEplModule

public AbstractEplModule()

AbstractEplModule

public AbstractEplModule(IEplContext context)

Method Detail

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<?>> 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> 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:

• getRoleInstances(Role, String)
  
• getNegativeRoleInstances(Role, String, Collection)
  
• getAllRoleInstances(Role, String, Collection)
  

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