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.
As of the 1.3 release, some of the customizations of the validator behaviour
are also implemented as
validation options. This provides a unified approach to this extensible
mechanism, simplifying the configuration of a validator by enabling
separation of the configuration step from the construction of the validator.
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)
|
Nested Class Summary
|
static class
|
IValidator.Option<
V>
The definition of a validator option. |
OPTION_REPORT_SUCCESSES
static final
IValidator.Option<
Boolean> OPTION_REPORT_SUCCESSES
- A boolean-valued option indicating whether to report the success
evaluation of constraints on target elements. The default value is
false.
-
Since:
- 1.3
-
See Also:
-
setOptions(Map)
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.
Since the 1.3 release, this method is equivalent to checking whether
the
OPTION_REPORT_SUCCESSES validation option is applied.
-
-
Returns:
- whether successful constraint evaluations are reported
-
See Also:
-
setReportSuccesses(boolean),
getOptions(),
OPTION_REPORT_SUCCESSES
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.
Since the 1.3 release, this method is equivalent to applying the
OPTION_REPORT_SUCCESSES validation option.
-
-
Parameters:
-
reportSuccesses - true to report successes;
false to ignore them -
See Also:
-
isReportSuccesses(),
setOptions(Map),
OPTION_REPORT_SUCCESSES
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)
getOptions
Map<
IValidator.Option<?>,?> getOptions()
- Obtains the options applied to me that customize my operation. The
resulting map is not modifiable by clients.
-
-
Returns:
- an unmodifiable view of my options
-
Since:
- 1.3
-
See Also:
-
setOptions(Map),
#getOption(Object, Object)
setOptions
void setOptions(
Map<
IValidator.Option<?>,?> options)
- Sets options to apply to me, that customize my operation.
-
-
Parameters:
-
options - my options, or null to set the defaults -
Since:
- 1.3
-
See Also:
-
getOptions(),
#setOption(Object, Object, Object)
getOption
<V> V getOption(
IValidator.Option<V> option)
- Convenience for querying an option.
-
-
Type Parameters:
-
V - the value type of the option -
Parameters:
-
option - the option key
-
Returns:
- the option's current value
-
Since:
- 1.3
-
See Also:
-
getOptions()
setOption
<V> void setOption(
IValidator.Option<? super V> option,
V value)
- Convenience for setting an option.
-
-
Type Parameters:
-
V - the value type of the option -
Parameters:
-
option - the option key -
value - the new value to set -
Since:
- 1.3
-
See Also:
-
setOptions(Map)
