Eclipse EMF Validation Framework (Galileo) - ITraversalStrategy (EMF Validation Framework Javadoc)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.emf.validation.service
Interface ITraversalStrategy

All Known Implementing Classes:: AbstractTraversalStrategy, ITraversalStrategy.Flat, ITraversalStrategy.Recursive

public interface ITraversalStrategy

A strategy for traversal of one or more model sub-trees in batch validation. The traversal strategy is responsible for providing elements to an IBatchValidator in whatever order the implementation defines, and also for updating the validation progress monitor periodically.

Note that traversal is performed over some number (possibly greater than one) of traversal roots. The validation system makes no assumption about the relationships between these roots (e.g., containment), so it is up to the strategy implementation to determine whether any optimization can be made in processing these sub-trees (e.g., determining that some roots will be covered by traversal of others).

See Also:: IBatchValidator.setTraversalStrategy(org.eclipse.emf.validation.service.ITraversalStrategy)

Nested Class Summary

static class ITraversalStrategy.Flat
          An implementation of the ITraversalStrategy interface that is non-recursive: it simply iterates the root elements.

static class ITraversalStrategy.Recursive
          An implementation of the ITraversalStrategy interface that is recursive: it iterates over the content trees of the roots, according to the basic EMF EObject.eAllContents() tree-iterator.

Method Summary

void elementValidated ( EObject element, IStatus status)
          Called by the validation system to indicate that another element has been validated.

boolean hasNext ()
          Queries whether there is another element to be validated.

boolean isClientContextChanged ()
          Queries whether the next element in the traversal will potentially be in a different client context than the one before.

EObject next ()
          Obtains the next element in the traversal.

void startTraversal ( Collection<? extends EObject> traversalRoots, IProgressMonitor monitor)
          Called at the start of validation to provide the sub-trees that are to be validated and a progress monitor to track the operation's progress.

Method Detail

startTraversal

void startTraversal(
Collection<? extends 
EObject> traversalRoots,
                    
IProgressMonitor monitor)

Called at the start of validation to provide the sub-trees that are to be validated and a progress monitor to track the operation's progress. The receiver must initialize the monitor by invoking the IProgressMonitor.beginTask(java.lang.String, int) method on it. Periodically, the receiver should also update the progress via the IProgressMonitor.worked(int) method. The validator will not make any attempt to update the progress, except that it will call IProgressMonitor.done() when validation is complete (the traversal strategy should not call done()).

Parameters:: traversalRoots - a collection of one or more EObjects. It is never empty, but neither is it modifiable; monitor - the progress monitor used to track progress. The receiver may retain this progress monitor for the duration of the traversal

hasNext

boolean hasNext()

Queries whether there is another element to be validated.

Returns:: true if another element can be obtained from the next() method; false, otherwise


EObject next()

Obtains the next element in the traversal. Should throw if hasNext() would return false.

Returns:: the next element in the traversal
Throws:: NoSuchElementException - if there are no more elements in the traversal

isClientContextChanged

boolean isClientContextChanged()

Queries whether the next element in the traversal will potentially be in a different client context than the one before. The validation framework will then re-compute the current client context. If there is no next element, then this method's return value is undefined.

At a minimum, every traversal root passed into the startTraversal(Collection, IProgressMonitor) method should be considered as a new client context.

A pessimistic implementation of this method may always return true. This results in absolutely correct validation, but may hamper performance where assumptions can be made about the delineation of client contexts.

A good rule-of-thumb for determining when the client context may change is as follows:

every traversal root defines a client context (see above)
any object traversed by a non-containment reference may change the client context
any object traversed by a containment relationship does not change the client context (it is in the same sub-tree), unless that element is an EAnnotation
EAnnotations are commonly used to bridge between metamodels. It is probably a good idea to return true for annotations and their contents (as no assumption about the nature of the metamodel and its client applications can be made)

Individual traversal strategies may be more or less optimistic than this rough guide, especially when they are contributed in tandem with client contexts by the same client application.

Returns:: true if the next object to be returned by the next() method is potentially in a different client context than the previous (thereby requiring the validation framework to recompute the context); false if the object can be assumed to be in the same context as the previous

elementValidated

void elementValidated(
EObject element,
                      
IStatus status)

Called by the validation system to indicate that another element has been validated. The receiver is encouraged to take this opportunity to update the progress monitor (the number of work units may vary each time).

Parameters:: element - the element that was validated; status - the element's validation status, indicating success or failure of its constraints. The receiver may with use this information to exclude or include portions of the model based on the status of the element