Package org.eclipse.m2m.atl.emftvm

# Interface Rule

All Superinterfaces:
  `org.eclipse.emf.ecore.EObject`, `NamedElement`, `org.eclipse.emf.common.notify.Notifier`

All Known Implementing Classes:
  `RuleImpl`

public interface Rule extends NamedElement
A representation of the model object 'Rule'.

See Also:
  - `EmftvmPackage.getRule()`

## Method Summary

Modifier and Type
Method
Description
`void`
`apply(StackFrame frame)`
Applies this rule for the created traces.
`boolean`
`applyFirst(StackFrame frame)`
Applies and post-applies this rule for the first recorded match.
`Object`
`applyFor(StackFrame frame, TraceLink trace)`
Applies this rule for the given `trace`.
`Object`
`applyOne(StackFrame frame, Map<String,Object> valuesMap)`
Applies this rule to `trace`
`void`
`clearFields()`
Clears the values of all registered fields within this rule.
`void`
`compileIterables(ExecEnv env)`
Compiles the model element iterables for this rule.
`void`
`compileState(ExecEnv env)`
Compiles the internal state of this rule for optimised matching.
`boolean`
`completeTraceFor(StackFrame frame, TraceLink trace)`
Completes `trace` for this rule by creating the output elements.
`void`
`createTraces(StackFrame frame)`
Creates trace elements for the recorded matches for this rule.
`void`
`createUniqueMapping(TraceLink trace)`
Creates a unique trace mapping entry for the source values in `trace`, if applicable.
`Field`
`findField(Object context, String name)`
Finds a `Field` registered within this `Rule`.
`InputRuleElement`
`findInputElement(String name)`
Finds the `InputRuleElement` with the given name within the rule inheritance hierarchy depth-first.
`Field`
`findStaticField(Object context, String name)`
Finds a static `Field` registered within this `Rule`.
`LazySet<Rule>`
`getAllESuperRules()`
Returns the transitive closure of super-rules, root rule first (`LazySet`'s have a fixed iteration order).
`CodeBlock`
`getApplier()`
Returns the value of the 'Applier' containment reference.
`org.eclipse.emf.common.util.EList<Rule>`
`getESubRules()`
Returns the value of the 'ESub Rules' reference list.
`org.eclipse.emf.common.util.EList<Rule>`
`getESuperRules()`
Returns the value of the 'ESuper Rules' reference list.
`org.eclipse.emf.common.util.EList<Field>`
`getFields()`
Returns the value of the 'Fields' containment reference list.
`org.eclipse.emf.common.util.EList<InputRuleElement>`
`getInputElements()`
Returns the value of the 'Input Elements' containment reference list.
`CodeBlock`
`getMatcher()`
Returns the value of the 'Matcher' containment reference.
`RuleMode`
`getMode()`
Returns the value of the 'Mode' attribute.
`Module`
`getModule()`
Returns the value of the 'Module' container reference.
`org.eclipse.emf.common.util.EList<OutputRuleElement>`
`getOutputElements()`
Returns the value of the 'Output Elements' containment reference list.
`CodeBlock`
`getPostApply()`
Returns the value of the 'Post Apply' containment reference.
`org.eclipse.emf.common.util.EList<String>`
`getSuperRules()`
Returns the value of the 'Super Rules' attribute list.
`TraceLink`
`getUniqueTrace(StackFrame frame, Object[] values)`
Returns the unique rule application trace for `values`, if applicable.
`boolean`
`hasField(String name)`
Returns `true` iff this rule has any registered fields with the given `name`.
`boolean`
`hasStaticField(String name)`
Returns `true` iff this rule has any registered static fields with the given `name`.
`boolean`
`isAbstract()`
Returns the value of the 'Abstract' attribute.
`boolean`
`isDefault()`
Returns the value of the 'Default' attribute.
`boolean`
`isDistinctElements()`
Returns the value of the 'Distinct Elements' attribute.
`boolean`
`isLeaf()`
Returns the value of the 'Leaf' attribute.
`boolean`
`isUnique()`
Returns the value of the 'Unique' attribute.
`boolean`
`isWithLeaves()`
Returns the value of the 'With Leaves' attribute.
`Object`
`matchManual(StackFrame frame, Object[] values)`
Matches this rule manually, if applicable.
`boolean`
`matchOne(StackFrame frame, Map<String,Object> valuesMap)`
Matches rule for `valuesMap`.
`boolean`
`matchOneOnly(StackFrame frame, Map<String,Object> valuesMap)`
Matches this rule only (without super-rules) for `valuesMap`.
`boolean[]`
`matchRecursive(StackFrame frame)`
Matches this rule for the automatic recursive stage, if applicable.
`boolean`
`matchSingle(StackFrame frame)`
Matches this rule for the automatic single stage, if applicable.
`void`
`postApply(StackFrame frame)`
Runs post-applier for this rule for the created traces.
`Object`
`postApplyFor(StackFrame frame, TraceLink trace)`
Post-applies this rule for the given `trace`.
`void`
`registerField(Field field)`
Registers a `Field` into this `Rule`.
`void`
`resetState()`
Resets the internal state of this rule.
`void`
`setAbstract(boolean value)`
Sets the value of the '`Abstract`' attribute.
`void`
`setApplier(CodeBlock value)`
Sets the value of the '`Applier`' containment reference.
`void`
`setDefault(boolean value)`
Sets the value of the '`Default`' attribute.
`void`
`setDistinctElements(boolean value)`
Sets the value of the '`Distinct Elements`' attribute.
`void`
`setMatcher(CodeBlock value)`
Sets the value of the '`Matcher`' containment reference.
`void`
`setMode(RuleMode value)`
Sets the value of the '`Mode`' attribute.
`void`
`setModule(Module value)`
Sets the value of the '`Module`' container reference.
`void`
`setPostApply(CodeBlock value)`
Sets the value of the '`Post Apply`' containment reference.
`void`
`setUnique(boolean value)`
Sets the value of the '`Unique`' attribute.

### Methods inherited from interface org.eclipse.emf.ecore.EObject

`eAllContents, eClass, eContainer, eContainingFeature, eContainmentFeature, eContents, eCrossReferences, eGet, eGet, eInvoke, eIsProxy, eIsSet, eResource, eSet, eUnset`

### Methods inherited from interface org.eclipse.m2m.atl.emftvm.NamedElement

`getName, setName`

### Methods inherited from interface org.eclipse.emf.common.notify.Notifier

`eAdapters, eDeliver, eNotify, eSetDeliver`

## Method Details

### getModule

Module getModule()
Returns the value of the 'Module' container reference. It is bidirectional and its opposite is '`Rules`'.

If the meaning of the 'Module' container reference isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Module' container reference.
See Also:
  - `setModule(Module)`
  - `EmftvmPackage.getRule_Module()`
  - `Module.getRules()`

### setModule

void setModule(Module value)
Sets the value of the '`Module`' container reference.

Parameters:
  `value` - the new value of the 'Module' container reference.
See Also:
  - `getModule()`

### getMode

RuleMode getMode()
Returns the value of the 'Mode' attribute. The literals are from the enumeration `RuleMode`.

If the meaning of the 'Mode' attribute isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Mode' attribute.
See Also:
  - `RuleMode`
  - `setMode(RuleMode)`
  - `EmftvmPackage.getRule_Mode()`

### setMode

void setMode(RuleMode value)
Sets the value of the '`Mode`' attribute.

Parameters:
  `value` - the new value of the 'Mode' attribute.
See Also:
  - `RuleMode`
  - `getMode()`

### getInputElements

org.eclipse.emf.common.util.EList<InputRuleElement> getInputElements()
Returns the value of the 'Input Elements' containment reference list. The list contents are of type `InputRuleElement`. It is bidirectional and its opposite is '`Input For`'.

If the meaning of the 'Input Elements' containment reference list isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Input Elements' containment reference list.
See Also:
  - `EmftvmPackage.getRule_InputElements()`
  - `InputRuleElement.getInputFor()`

### getOutputElements

org.eclipse.emf.common.util.EList<OutputRuleElement> getOutputElements()
Returns the value of the 'Output Elements' containment reference list. The list contents are of type `OutputRuleElement`. It is bidirectional and its opposite is '`Output For`'.

If the meaning of the 'Output Elements' containment reference list isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Output Elements' containment reference list.
See Also:
  - `EmftvmPackage.getRule_OutputElements()`
  - `OutputRuleElement.getOutputFor()`

### getESuperRules

org.eclipse.emf.common.util.EList<Rule> getESuperRules()
Returns the value of the 'ESuper Rules' reference list. The list contents are of type `Rule`. It is bidirectional and its opposite is '`ESub Rules`'.

If the meaning of the 'ESuper Rules' reference list isn't clear, there really should be more of a description here...

Returns:
  the value of the 'ESuper Rules' reference list.
See Also:
  - `EmftvmPackage.getRule_ESuperRules()`
  - `getESubRules()`

### getESubRules

org.eclipse.emf.common.util.EList<Rule> getESubRules()
Returns the value of the 'ESub Rules' reference list. The list contents are of type `Rule`. It is bidirectional and its opposite is '`ESuper Rules`'.

If the meaning of the 'ESub Rules' reference list isn't clear, there really should be more of a description here...

Returns:
  the value of the 'ESub Rules' reference list.
See Also:
  - `EmftvmPackage.getRule_ESubRules()`
  - `getESuperRules()`

### getMatcher

CodeBlock getMatcher()
Returns the value of the 'Matcher' containment reference. It is bidirectional and its opposite is '`Matcher For`'.

If the meaning of the 'Matcher' containment reference isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Matcher' containment reference.
See Also:
  - `setMatcher(CodeBlock)`
  - `EmftvmPackage.getRule_Matcher()`
  - `CodeBlock.getMatcherFor()`

### setMatcher

void setMatcher(CodeBlock value)
Sets the value of the '`Matcher`' containment reference.

Parameters:
  `value` - the new value of the 'Matcher' containment reference.
See Also:
  - `getMatcher()`

### getApplier

CodeBlock getApplier()
Returns the value of the 'Applier' containment reference. It is bidirectional and its opposite is '`Applier For`'.

If the meaning of the 'Applier' containment reference isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Applier' containment reference.
See Also:
  - `setApplier(CodeBlock)`
  - `EmftvmPackage.getRule_Applier()`
  - `CodeBlock.getApplierFor()`

### setApplier

void setApplier(CodeBlock value)
Sets the value of the '`Applier`' containment reference.

Parameters:
  `value` - the new value of the 'Applier' containment reference.
See Also:
  - `getApplier()`

### getPostApply

CodeBlock getPostApply()
Returns the value of the 'Post Apply' containment reference. It is bidirectional and its opposite is '`Post Apply For`'.

If the meaning of the 'Post Apply' containment reference isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Post Apply' containment reference.
See Also:
  - `setPostApply(CodeBlock)`
  - `EmftvmPackage.getRule_PostApply()`
  - `CodeBlock.getPostApplyFor()`

### setPostApply

void setPostApply(CodeBlock value)
Sets the value of the '`Post Apply`' containment reference.

Parameters:
  `value` - the new value of the 'Post Apply' containment reference.
See Also:
  - `getPostApply()`

### getSuperRules

org.eclipse.emf.common.util.EList<String> getSuperRules()
Returns the value of the 'Super Rules' attribute list. The list contents are of type `String`.

If the meaning of the 'Super Rules' reference list isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Super Rules' attribute list.
See Also:
  - `EmftvmPackage.getRule_SuperRules()`

### isAbstract

boolean isAbstract()
Returns the value of the 'Abstract' attribute.

If the meaning of the 'Abstract' attribute isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Abstract' attribute.
See Also:
  - `setAbstract(boolean)`
  - `EmftvmPackage.getRule_Abstract()`

### setAbstract

void setAbstract(boolean value)
Sets the value of the '`Abstract`' attribute.

Parameters:
  `value` - the new value of the 'Abstract' attribute.
See Also:
  - `isAbstract()`

### getFields

org.eclipse.emf.common.util.EList<Field> getFields()
Returns the value of the 'Fields' containment reference list. The list contents are of type `Field`. It is bidirectional and its opposite is '`Rule`'.

If the meaning of the 'Fields' containment reference list isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Fields' containment reference list.
See Also:
  - `EmftvmPackage.getRule_Fields()`
  - `Field.getRule()`

### isDefault

boolean isDefault()
Returns the value of the 'Default' attribute.

If the meaning of the 'Default' attribute isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Default' attribute.
See Also:
  - `setDefault(boolean)`
  - `EmftvmPackage.getRule_Default()`

### setDefault

void setDefault(boolean value)
Sets the value of the '`Default`' attribute.

Parameters:
  `value` - the new value of the 'Default' attribute.
See Also:
  - `isDefault()`

### isDistinctElements

boolean isDistinctElements()
Returns the value of the 'Distinct Elements' attribute.

If the meaning of the 'Distinct Elements' attribute isn't clear, there really should be more of a description here...

Returns:
  the value of the 'Distinct Elements' attribute.
See Also:
  - `setDistinctElements(boolean)`
  - `EmftvmPackage.getRule_DistinctElements()`

### setDistinctElements

void setDistinctElements(boolean value)
Sets the value of the '`Distinct Elements`' attribute.

Parameters:
  `value` - the new value of the 'Distinct Elements' attribute.
See Also:
  - `isDistinctElements()`

### isUnique

boolean isUnique()
Returns the value of the 'Unique' attribute.

A unique rule matches at most once against a unique (list of) source value(s). Traces created by a unique rule can also be efficiently lookup up, because each (list of) source value(s) maps to at most one (list of) target value(s).

Returns:
  the value of the 'Unique' attribute.
See Also:
  - `setUnique(boolean)`
  - `EmftvmPackage.getRule_Unique()`

### setUnique

void setUnique(boolean value)
Sets the value of the '`Unique`' attribute.

Parameters:
  `value` - the new value of the 'Unique' attribute.
See Also:
  - `isUnique()`

### isLeaf

boolean isLeaf()
Returns the value of the 'Leaf' attribute.

A rule is a leaf rule when it is not abstract, and it has no leaf sub-rules. Call `#compileState()` before calling this method.

Returns:
  the value of the 'Leaf' attribute.
See Also:
  - `EmftvmPackage.getRule_Leaf()`

### isWithLeaves

boolean isWithLeaves()
Returns the value of the 'With Leaves' attribute.

A rule is with leaves if it has leaf sub-rules. Call `#compileState()` before calling this method.

Returns:
  the value of the 'With Leaves' attribute.
See Also:
  - `EmftvmPackage.getRule_WithLeaves()`

### findField

Field findField(Object context, String name)
Finds a `Field` registered within this `Rule`.

Parameters:
  `context` - the context type of the field
  `name` - the operation name
Returns:
  the `Field` with the given properties, or `null` if none registered

### hasField

boolean hasField(String name)
Returns `true` iff this rule has any registered fields with the given `name`.

Parameters:
  `name` - the field name
Returns:
  `true` iff this rule has any registered fields with the given `name`

### findStaticField

Field findStaticField(Object context, String name)
Finds a static `Field` registered within this `Rule`.

Parameters:
  `context` - the context type of the field
  `name` - the operation name
Returns:
  the static `Field` with the given properties, or `null` if none registered

### hasStaticField

boolean hasStaticField(String name)
Returns `true` iff this rule has any registered static fields with the given `name`.

Parameters:
  `name` - the field name
Returns:
  `true` iff this rule has any registered static fields with the given `name`

### registerField

void registerField(Field field)
Registers a `Field` into this `Rule`.

Parameters:
  `field` - the `Field` to register

### matchSingle

boolean matchSingle(StackFrame frame)
Matches this rule for the automatic single stage, if applicable. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the matcher
Returns:
  `true` iff the rule has any matches

### matchRecursive

boolean[] matchRecursive(StackFrame frame)
Matches this rule for the automatic recursive stage, if applicable. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the matcher
Returns:
  [`true` iff the rule has any matches, `true` iff there was a guaranteed final match]

### matchManual

Object matchManual(StackFrame frame, Object[] values)
Matches this rule manually, if applicable. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the matcher
  `values` - the values to match against
Returns:
  the rule application result, or `null` if the rule did not match
Throws:
  `VMException` - if this is not a `RuleMode.MANUAL` rule

### matchOne

boolean matchOne(StackFrame frame, Map<String,Object> valuesMap)
Matches rule for `valuesMap`. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the matcher
  `valuesMap` - the values to match against
Returns:
  `true` iff the rule matches

### matchOneOnly

boolean matchOneOnly(StackFrame frame, Map<String,Object> valuesMap)
Matches this rule only (without super-rules) for `valuesMap`. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the matcher
  `valuesMap` - the values to match against
Returns:
  `true` iff the rule matches

### createTraces

void createTraces(StackFrame frame)
Creates trace elements for the recorded matches for this rule. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame context
Throws:
  `VMException` - if no matches are recorded for this rule

### completeTraceFor

boolean completeTraceFor(StackFrame frame, TraceLink trace)
Completes `trace` for this rule by creating the output elements. Will create default/unique trace iff mapsTo information exists. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame context
  `trace` - the trace to complete
Returns:
  `true` iff default/unique mappings were defined for the complete list of source elements

### apply

void apply(StackFrame frame)
Applies this rule for the created traces. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the applier
Throws:
  `VMException` - if no traces exist for this rule

### postApply

void postApply(StackFrame frame)
Runs post-applier for this rule for the created traces. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the post-applier
Throws:
  `VMException` - if no traces exist for this rule

### applyFirst

boolean applyFirst(StackFrame frame)
Applies and post-applies this rule for the first recorded match. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame in which to execute the applier and post-applier
Returns:
  `true` iff this rule was applied
Throws:
  `VMException` - if no matches are recorded for this rule

### applyOne

Object applyOne(StackFrame frame, Map<String,Object> valuesMap)
Applies this rule to `trace`

Parameters:
  `frame` - the stack frame in which to execute the applier and post-apply
  `valuesMap` - the source and target values to which to apply the rule
Returns:
  the rule application result

### applyFor

Object applyFor(StackFrame frame, TraceLink trace)
Applies this rule for the given `trace`. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame context
  `trace` - the trace link to apply the rule for
Returns:
  the application result

### postApplyFor

Object postApplyFor(StackFrame frame, TraceLink trace)
Post-applies this rule for the given `trace`. Call `#compileState()` before calling this method.

Parameters:
  `frame` - the stack frame context
  `trace` - the trace link to post-apply the rule for
Returns:
  the post-application result

### getAllESuperRules

LazySet<Rule> getAllESuperRules()
Returns the transitive closure of super-rules, root rule first (`LazySet`'s have a fixed iteration order). Call `#compileState()` before calling this method.

Returns:
  the transitive closure of super-rules.

### createUniqueMapping

void createUniqueMapping(TraceLink trace)
Creates a unique trace mapping entry for the source values in `trace`, if applicable.

Parameters:
  `trace` - the trace element with source values

### compileState

void compileState(ExecEnv env)
Compiles the internal state of this rule for optimised matching. Call this method whenever any properties of this rule or any sub-rules have changed.

Parameters:
  `env` - the execution environment context

### resetState

void resetState()
Resets the internal state of this rule. Call this method before calling `compileState(ExecEnv)` on all rules.

### compileIterables

void compileIterables(ExecEnv env)
Compiles the model element iterables for this rule. Call this method whenever any input or in/out model has changed.

Parameters:
  `env` - the execution environment context

### clearFields

void clearFields()
Clears the values of all registered fields within this rule.

### findInputElement

InputRuleElement findInputElement(String name)
Finds the `InputRuleElement` with the given name within the rule inheritance hierarchy depth-first.

Parameters:
  `name` - the input element name
Returns:
  the `InputRuleElement` with the given name or `null`

### getUniqueTrace

TraceLink getUniqueTrace(StackFrame frame, Object[] values)
Returns the unique rule application trace for `values`, if applicable.

Parameters:
  `frame` - the stack frame context
  `values` - the source values for the trace
Returns:
  the unique rule application trace, or `null`