org.eclipse.emf.validation.service
Interface IValidator<T>

Type Parameters:
T - the kind of target element validated by the validator
All Known Subinterfaces:
IBatchValidator, ILiveValidator

public interface IValidator<T>

A validator validates model elements on behalf of the validation service's clients. The validator supports a variety of controls determining how the validation is done; for example, whether only validation problems are reported or also which constraints are satisfied, whether batch validation is recursive, etc.

The different specializations of this interface evaluate constraints for the various modes of validation, and are obtained from the ModelValidationService. Typically, a client will obtain a new validator and retain it for repeated use (probably for the lifetime of the client object). In general, validators are not thread-safe.

The result of the validate(T) method is an IStatus containing the results (as individual status objects) of every constraint that failed and, if enabled, also those that passed. The validator guarantees that the same constraint is not evaluated twice on the same model object for the same trigger.

Validation clients are encouraged to put information into the validators that they create, that will help validation listeners to know how to interpret validation results. This information can be provided by the putClientData(String, Object) method. As an example, a client may wish to publish the marker type ID under which a listener should create or look for validation problem markers, especially for batch validation.

In the future, the validator may provide additional services, such as statistics, diagnostics, and other meta-data about the validation operation.

Note that clients are not intended to implement this interface.

See Also:
ModelValidationService.newValidator(EvaluationMode)

Method Summary
 void addConstraintFilter(IConstraintFilter filter)
          Adds a constraint filter to this validator.
 Object getClientData(String key)
          Allows a client to retrieve "client data" that it had previously put.
 Collection<IConstraintFilter> getConstraintFilters()
          Obtains a collection of IConstraintFilters that define which constraints should be excluded for validation.
 EvaluationMode<T> getEvaluationMode()
          Indicates the evaluation mode that I support.
 boolean isReportSuccesses()
          Queries whether successful constraint evaluations are reported, in addition to validation problems.
 void putClientData(String key, Object data)
          Makes the specified named particle of information available to listeners who will receiver validation events from this validator.
 void removeConstraintFilter(IConstraintFilter filter)
          Removes a constraint filter from this validator.
 void setReportSuccesses(boolean reportSuccesses)
          Indicates whether successful constraint evaluations are to be reported, in addition to validation problems.
 IStatus validate(Collection<? extends T> objects)
          Validates multiple objects, all in the same validation context.
 IStatus validate(T object)
          Validates an object.
 

Method Detail

getEvaluationMode

EvaluationMode<T> getEvaluationMode()
Indicates the evaluation mode that I support. This indicates the kind of objects expected by the validate() methods to process.

Returns:
my evaluation mode

isReportSuccesses

boolean isReportSuccesses()
Queries whether successful constraint evaluations are reported, in addition to validation problems.

Returns:
whether successful constraint evaluations are reported
See Also:
setReportSuccesses(boolean)

setReportSuccesses

void setReportSuccesses(boolean reportSuccesses)
Indicates whether successful constraint evaluations are to be reported, in addition to validation problems. If false, then the status reported by the validate() methods will not contain sub-statuses representing the constraints that passed, but will only have sub-statuses for the constraints (if any) that failed.

Parameters:
reportSuccesses - true to report successes; false to ignore them

putClientData

void putClientData(String key,
                   Object data)
Makes the specified named particle of information available to listeners who will receiver validation events from this validator. This is useful to communicate some contextual information about the validation client to listeners, to better interpret the validation events.

Parameters:
key - identifies an entry in the data map; must not be null
data - the associated data, or null to remove it

getClientData

Object getClientData(String key)
Allows a client to retrieve "client data" that it had previously put.

Parameters:
key - the key under which the data object was put
Returns:
the corresponding data, or null if none was put under this key
See Also:
putClientData(String, Object)

validate

IStatus validate(T object)
Validates an object. The type of object that is expected various by implementation.

Parameters:
object - the object to validate
Returns:
the status of validation. The severity of the result indicates whether validation passed or (how badly it) failed. Normally, the result is a multi-status whose children are the results of individual constraint evaluations
Throws:
ClassCastException - if the object is not of the correct type for this validator

validate

IStatus validate(Collection<? extends T> objects)
Validates multiple objects, all in the same validation context. This method is preferable to repeated invocations of validate(Object) because it avoids repetition of constraints (as well as results) and other performance optimizations.

Parameters:
objects - the objects to be validated
Returns:
a collective status of the validation operation, which usually is a multi-status of individual results
Throws:
ClassCastException - if any of the objects is not of the correct type for this validator
See Also:
validate(Object)

addConstraintFilter

void addConstraintFilter(IConstraintFilter filter)
Adds a constraint filter to this validator. The validator will only evaluate constraints that are accepted by its constraint filters. If a validator has no filters, then all constraints are validated.

Parameters:
filter - the constraint filter to add
Since:
1.1

removeConstraintFilter

void removeConstraintFilter(IConstraintFilter filter)
Removes a constraint filter from this validator. If a validator has no filters, then all constraints are validated.

Parameters:
filter - the constraint filter to remove
Since:
1.1
See Also:
addConstraintFilter(IConstraintFilter)

getConstraintFilters

Collection<IConstraintFilter> getConstraintFilters()
Obtains a collection of IConstraintFilters that define which constraints should be excluded for validation.

Returns:
my constraint filters. This list is not modifiable
Since:
1.1
See Also:
addConstraintFilter(IConstraintFilter), removeConstraintFilter(IConstraintFilter)

Copyright 2002, 2007 IBM Corporation and others.
All Rights Reserved.