org.eclipse.emf.validation
Interface IValidationContext

public interface IValidationContext

Interface providing contextual information to AbstractModelConstraints about the validation currently in progress. Also provides some useful services to manipulate a constraint's environment.

The context knows at any point in time what constraint is currently being evaluated on which model element. Thus, the context will seem to know what constraint implementation is calling it, but this is just a consequence of the fact that constraints are invoked strictly one at a time by the context, itself.

A single constraint implementation may check multiple conditions. In such cases, it can return a multi-status of multiple results created by the overloaded variants of the ConstraintStatus.createStatus(IValidationContext, Collection, String, Object[]) method.

Note that the results of any method calls on the context object are only valid during the invocation of the constraint's validate() method. The results should not be retained by a constraint implementation.

This interface should not be implemented outside of the validation framework.

Method Summary

void	addResult(EObject eObject) Adds a result to the result locus of the current constraint.
void	addResults(Collection<? extends EObject> eObjects) Adds all of the specified model elements to the result locus of the current constraint.
IStatus	createFailureStatus(Object... messageArgument) Creates a status object indicating unsuccessful evaluation of the current constraint on the current target element.
IStatus	createSuccessStatus() Creates a status object indicating successful evaluation of the current constraint on the current target element.
void	disableCurrentConstraint(Throwable exception) Causes the current constraint to be disabled for the remainder of the Eclipse session, because it is no longer viable due to some run-time exception.
List<Notification>	getAllEvents() Gets all of the Notifications that are currently being validated.
Object	getCurrentConstraintData() Gets the current constraint's private working data.
String	getCurrentConstraintId() Obtains the ID of the constraint currently being evaluated.
EMFEventType	getEventType() In the case of a live constraint evaluation, obtains the type of event which is currently being validated.
EStructuralFeature	getFeature() In the case of a live constraint evaluation, obtains the particular feature on which the constraint is triggered.
Object	getFeatureNewValue() In the case of live constraint evaluation that is triggered by a particular feature, obtains the new value of the feature that is being validated.
Set<EObject>	getResultLocus() Obtains the result locus of this evaluation of the current constraint.
EObject	getTarget() Obtains the EMF object currently being validated.
Object	putCurrentConstraintData(Object newData) Puts into this context some working data that is to be cached for the current constraint.
void	skipCurrentConstraintFor(EObject eObject) Causes the current constraint to be skipped in any subsequent validation of the specified eObject in the current validation operation.
void	skipCurrentConstraintForAll(Collection<?> eObjects) Causes the current constraint to be skipped in any subsequent validation of any of the specified eObjects in the current validation operation.

Method Detail

getCurrentConstraintId

String getCurrentConstraintId()

Obtains the ID of the constraint currently being evaluated. This is useful for a class that implements multiple different constraints to determine for which constraint it is being invoked.

Returns:

the ID of the constraint currently being evaluated

See Also:

AbstractModelConstraint

getTarget

EObject getTarget()

Obtains the EMF object currently being validated.

Returns:

the current validation target

getEventType

EMFEventType getEventType()

In the case of a live constraint evaluation, obtains the type of event which is currently being validated.

Returns:

the live constraint's triggering event type, or EMFEventType.NULL if the constraint is being evaluated in batch mode

getAllEvents

List<Notification> getAllEvents()

Gets all of the Notifications that are currently being validated. This is useful for live constraints that need more contextual information about the changes being validated than is available in a single notification.

Returns:

the raw Notifications being validated, or an empty list if this is a batch validation. This list is not modifiable

getFeature

EStructuralFeature getFeature()

In the case of a live constraint evaluation, obtains the particular feature on which the constraint is triggered. Note that this only applies to constraints that are triggered by specific features; the result will be null if the constraint does not specify any feature triggers in the XML meta-data.

Returns:

the feature constraint's triggering feature, or null if the constraint is not triggered by a particular feature

See Also:

getFeatureNewValue()

getFeatureNewValue

Object getFeatureNewValue()

In the case of live constraint evaluation that is triggered by a particular feature, obtains the new value of the feature that is being validated. The exact contents of the result are as follows:

• Add or Add Many: in the "Add" case, a single object added to the feature. In "Add Many" case, a collection of objects added
• Remove or Remove Many: in the "Remove" case, a single object removed from the feature. In "Remove Many" case, a collection of objects removed
• Set, Unset, or Move: the final value of the feature at the end of the transaction (i.e., its current value)
• Create: a single object or a collection of objects created in the feature
• Resolved: a single object or a collection of objects resolved in the feature
• Resolving Adapter: a single adapter or a collection of adapters removed from the adapter list of the target
• Others: the final value of the feature at the end of the transaction (i.e., its current value)

.

Returns:

the feature constraint's triggering new value (as a single object or a Collection), or null if the constraint is not triggered by a particular feature

See Also:

getFeature()

skipCurrentConstraintFor

void skipCurrentConstraintFor(EObject eObject)

Causes the current constraint to be skipped in any subsequent validation of the specified eObject in the current validation operation. Constraints can use this facility to short-circuit processing, especially in a recursive batch validation, of objects that they have already checked in processing the current target.

For example, checking for dependency cycles in a UML model requires traversing the dependency relationships from an element as far as they reach throughout the model. Every element thus traversed can subsequently be ignored by the constraint, as ground that needs not be trodden again, whether a cycle was found or not.

Note that there is no need to invoke this method for the current target object; the validation system guarantees that it will not be revisited.

Parameters:

eObject - the model object to be skipped by the current constraint

skipCurrentConstraintForAll

void skipCurrentConstraintForAll(Collection<?> eObjects)

Causes the current constraint to be skipped in any subsequent validation of any of the specified eObjects in the current validation operation.

Parameters:

eObjects - the model objects to be skipped by the current constraint

See Also:

skipCurrentConstraintFor(EObject)

disableCurrentConstraint

void disableCurrentConstraint(Throwable exception)

Causes the current constraint to be disabled for the remainder of the Eclipse session, because it is no longer viable due to some run-time exception.

Note how this differs from the skipCurrentConstraintFor(EObject) method: the current constraint is skipped for all model elements and even in subsequent validation operations.

Parameters:

exception - the exception that has caused the current constraint to be non-viable. Must not be null

getCurrentConstraintData

Object getCurrentConstraintData()

Gets the current constraint's private working data. This object can be anything that the caller defines. The value is null until it is set by this same constraint using the putCurrentConstraintData(java.lang.Object) method. The working data persists only for the duration of the validation operation.

The constraint may use this to cache any data that may be of use to it in optimizing the processing of multiple objects, reporting information to the user, etc.

Returns:

the current constraint's working data

See Also:

putCurrentConstraintData(Object)

putCurrentConstraintData

Object putCurrentConstraintData(Object newData)

Puts into this context some working data that is to be cached for the current constraint. The data may be retrieved later by a call to the getCurrentConstraintData() method during the same validation operation.

Parameters:

newData - the new working data

Returns:

the previous constraint data object that the newData is displacing

getResultLocus

Set<EObject> getResultLocus()

Obtains the result locus of this evaluation of the current constraint. The returned set is not modifiable.

Returns:

an unmodifiable view of the result locus

See Also:

addResult(EObject)

addResult

void addResult(EObject eObject)

Adds a result to the result locus of the current constraint. The result locus is the set of model elements that contribute to the violation of a constraint. The current target is implicitly added to the result locus if the constraint evaluation fails.

Parameters:

eObject - the model element to add to the result locus

See Also:

getResultLocus()

addResults

void addResults(Collection<? extends EObject> eObjects)

Adds all of the specified model elements to the result locus of the current constraint.

Parameters:

eObjects - the model elements to add to the result locus. Must contain elements of type EObject

See Also:

addResult(EObject)

createSuccessStatus

IStatus createSuccessStatus()

Creates a status object indicating successful evaluation of the current constraint on the current target element.

Returns:

the "success" status

createFailureStatus

IStatus createFailureStatus(Object... messageArgument)

Creates a status object indicating unsuccessful evaluation of the current constraint on the current target element. The status will have the severity, error code, and message defined in the constraint meta-data in the XML.

Parameters:

messageArgument - the positional {0}, {1}, etc. arguments to replace in the message pattern (may by null if none are needed)

Returns:

the status indicating a constraint violation