org.eclipse.ocl.examples.impactanalyzer.instanceScope

Interface NavigationStep

All Superinterfaces:

SemanticComparable

All Known Implementing Classes:

AbsoluteNavigationStep, AbstractNavigationStep, AllInstancesNavigationStep, AssociationNavigationStep, BranchingNavigationStep, CompositeNavigationStep, EmptyResultNavigationStep, IdentityNavigationStep, IndirectingStep, NavigationStepSequence, OppositePropertyNavigationStep, PredicateCheckNavigationStep, RefImmediateCompositeNavigationStep

public interface NavigationStep
extends SemanticComparable

During instance scope analysis, starting from an event's source element, by navigation the analyzer is trying to find a small superset of those context elements for which re-evaluating the OCL expression may yield a different value after the event compared to the value the OCL expression would have returned before the event. This navigation is performed by following a set of pre-computed paths. The paths are precomputed because many subexpressions in an OCL expression do not reasonably contribute to the finding of those contexts and should therefore be pruned during an analysis that is performend only once per expression.

Navigation steps are generally able to navigate from one or more EObjects to zero or more EObjects. Each navigation step knows its static start and end type. If the source element's type doesn't conform to the step's start type, the navigation is not performed and an empty set is returned immediately. If the target type is not matched, an empty set is returned, too.

Navigation steps may form a possibly cyclic (in case of recursive operations) graph. Steps may navigate, e.g., along associations or ascend the composition hierarchy, using RefObject#refImmediateComposite().

A navigation step object may change its Object.hashCode() over its life time. This particularly has to do with the propagation of information taking place after an IndirectingStep has its actual step set. This can lead to a ripple effect regarding source and target type settings as well as isAlwaysEmpty() changes, all affecting a step's hash code and equality definition. Whenever you insert a navigation step into a hashing structure such as a HashMap or a HashSet, ensure that you use addHashCodeChangeListener(HashCodeChangeListener) to register yourself as a listener for hash code changes. Whenever such a change is signalled, take this as an opportunity to first remove (before the change) the navigation step object from the hashing structure and then insert it again with the new hash code after the change. See also HashCodeChangeListener.

Method Summary

Modifier and Type	Method and Description
void	addAlwaysEmptyChangeListener(AlwaysEmptyChangeListener listener) Whenever the result of isAlwaysEmpty() changes, registered listeners will be informed by calling their AlwaysEmptyChangeListener.alwaysEmptyChanged(NavigationStep) method with this step as parameter.
void	addEnteringScopes(java.util.Set<Variable> enteringScope) Sets the set of variables that come into scope when this navigation step is navigated.
void	addExpressionForWhichThisIsNavigationStep(OCLExpression oclExpression) Adds oclExpression as an expression for which this is the computed navigation step.
void	addHashCodeChangeListener(HashCodeChangeListener listener)
void	addLeavingScopes(java.util.Set<Variable> leavingScopes) Adds variables to the set of variables leaving scope when navigating this step.
void	addSourceTypeChangeListener(SourceTypeChangeListener listener) Whenever the result of getSourceType() changes, registered listeners will be informed by calling their SourceTypeChangeListener.sourceTypeChanged(NavigationStep) method with this step as parameter.
void	addTargetTypeChangeListener(TargetTypeChangeListener listener) Whenever the result of getTargetType() changes, registered listeners will be informed by calling their TargetTypeChangeListener.targetTypeChanged(NavigationStep) method with this step as parameter.
int	distinctSize()
java.util.Set<OCLExpression>	getDebugInfo() Optionally, a navigation step may tell for which OCL expression it was mainly created.
java.util.Set<Variable>	getEnteringScopes() Returns the variables that come into scope when this navigation step is navigated.
java.util.Set<Variable>	getLeavingScopes() Returns the variables that fall out of scope when navigating this step.
org.eclipse.emf.ecore.EClass	getSourceType()
org.eclipse.emf.ecore.EClass	getTargetType()
boolean	isAbsolute() Some "navigation" steps produce absolute results, ignoring the from object that is passed to navigate(Set, TracebackCache, Notification).
boolean	isAlwaysEmpty() Tells if this step in all cases returns an empty set.
java.util.Set<AnnotatedEObject>	navigate(java.util.Set<AnnotatedEObject> from, TracebackCache cache, org.eclipse.emf.common.notify.Notification changeEvent)
int	size() Counts the number of steps in the navigation step tree of which this is the root

Methods inherited from interface org.eclipse.ocl.examples.impactanalyzer.util.SemanticComparable

getSemanticIdentity

Method Detail

navigate

java.util.Set<AnnotatedEObject> navigate(java.util.Set<AnnotatedEObject> from,
                                         TracebackCache cache,
                                         org.eclipse.emf.common.notify.Notification changeEvent)

Parameters:

cache - keys are lists of which the first element (index 0) is the NavigationStep, the second element (index 1) the from-object (of type AnnotatedEObject) for which to look up any previously computed results.

isAbsolute

boolean isAbsolute()

Some "navigation" steps produce absolute results, ignoring the from object that is passed to navigate(Set, TracebackCache, Notification). Those must return true here. Examples are navigation steps returning all instances of a given type and the step always returning the empty set.

isAlwaysEmpty

boolean isAlwaysEmpty()

Tells if this step in all cases returns an empty set. Specific shortcuts may be taken for such steps when combining them with other steps.

isAlwaysEmpty() implies isAbsolute()

getSourceType

org.eclipse.emf.ecore.EClass getSourceType()

getTargetType

org.eclipse.emf.ecore.EClass getTargetType()

getDebugInfo

java.util.Set<OCLExpression> getDebugInfo()

Optionally, a navigation step may tell for which OCL expression it was mainly created. This can aid the impact analysis debugging process. May return null.

addAlwaysEmptyChangeListener

void addAlwaysEmptyChangeListener(AlwaysEmptyChangeListener listener)

Whenever the result of isAlwaysEmpty() changes, registered listeners will be informed by calling their AlwaysEmptyChangeListener.alwaysEmptyChanged(NavigationStep) method with this step as parameter.

addSourceTypeChangeListener

void addSourceTypeChangeListener(SourceTypeChangeListener listener)

Whenever the result of getSourceType() changes, registered listeners will be informed by calling their SourceTypeChangeListener.sourceTypeChanged(NavigationStep) method with this step as parameter.

addTargetTypeChangeListener

void addTargetTypeChangeListener(TargetTypeChangeListener listener)

Whenever the result of getTargetType() changes, registered listeners will be informed by calling their TargetTypeChangeListener.targetTypeChanged(NavigationStep) method with this step as parameter.

addHashCodeChangeListener

void addHashCodeChangeListener(HashCodeChangeListener listener)

size

int size()

Counts the number of steps in the navigation step tree of which this is the root

distinctSize

int distinctSize()

addExpressionForWhichThisIsNavigationStep

void addExpressionForWhichThisIsNavigationStep(OCLExpression oclExpression)

Adds oclExpression as an expression for which this is the computed navigation step. Multiple expressions may share the same navigation step. An expression added here will be returned in the set resulting from getDebugInfo().

getLeavingScopes

java.util.Set<Variable> getLeavingScopes()

Returns the variables that fall out of scope when navigating this step. Scopes are given in form of Variables. Note that variables leaving scope can immediately come into scope again, thus occurring in the results of getLeavingScopes() as well as getEnteringScopes(). It just means that the variable shows up in a new dynamic scope.

Returns:

the set of Variables that represents the scopes left by navigating this step.

addLeavingScopes

void addLeavingScopes(java.util.Set<Variable> leavingScopes)

Adds variables to the set of variables leaving scope when navigating this step. Scopes are given in form of Variables. Note that variables leaving scope can immediately come into scope again, thus occurring in the results of getLeavingScopes() as well as getEnteringScopes(). It just means that the variable shows up in a new dynamic scope.

Parameters:

leavingScopes - the set of Variables that fall out of scope by navigating this step.

getEnteringScopes

java.util.Set<Variable> getEnteringScopes()

Returns the variables that come into scope when this navigation step is navigated. It is given as an Variable.

Returns:

the Variables coming entering scope by navigating this step.

addEnteringScopes

void addEnteringScopes(java.util.Set<Variable> enteringScope)

Sets the set of variables that come into scope when this navigation step is navigated. It is given as an Set>Variable>.

Parameters:

enteringScope - the set of Variables representing the variables getting into scope by navigating this step.