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

All Methods Instance Methods Abstract Methods
`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.
`java.lang.Object` `applyFor​(StackFrame frame, TraceLink trace)` Applies this rule for the given `trace`.
`java.lang.Object` `applyOne​(StackFrame frame, java.util.Map<java.lang.String,​java.lang.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​(java.lang.Object context, java.lang.String name)` Finds a `Field` registered within this `Rule`.
`InputRuleElement` `findInputElement​(java.lang.String name)` Finds the `InputRuleElement` with the given name within the rule inheritance hierarchy depth-first.
`Field` `findStaticField​(java.lang.Object context, java.lang.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<java.lang.String>` `getSuperRules()` Returns the value of the 'Super Rules' attribute list.
`TraceLink` `getUniqueTrace​(StackFrame frame, java.lang.Object[] values)` Returns the unique rule application trace for `values`, if applicable.
`boolean` `hasField​(java.lang.String name)` Returns `true` iff this rule has any registered fields with the given `name`.
`boolean` `hasStaticField​(java.lang.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.
`java.lang.Object` `matchManual​(StackFrame frame, java.lang.Object[] values)` Matches this rule manually, if applicable.
`boolean` `matchOne​(StackFrame frame, java.util.Map<java.lang.String,​java.lang.Object> valuesMap)` Matches rule for `valuesMap`.
`boolean` `matchOneOnly​(StackFrame frame, java.util.Map<java.lang.String,​java.lang.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.
`java.lang.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 Detail

#### 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<java.lang.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​(java.lang.Object context,
                    java.lang.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​(java.lang.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​(java.lang.Object context,
                          java.lang.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​(java.lang.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

    java.lang.Object matchManual​(StackFrame frame,
                                 java.lang.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,
                     java.util.Map<java.lang.String,​java.lang.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,
                         java.util.Map<java.lang.String,​java.lang.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

    java.lang.Object applyOne​(StackFrame frame,
                              java.util.Map<java.lang.String,​java.lang.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

    java.lang.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

    java.lang.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​(java.lang.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,
                             java.lang.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`