org.eclipse.emf.validation.service
Interface IValidator

All Known Subinterfaces:
IBatchValidator, ILiveValidator

public interface IValidator

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 IValidator.validate(java.lang.Object) 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 IValidator.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
 java.lang.Object getClientData(java.lang.String key)
          Allows a client to retrieve "client data" that it had previously put.
 EvaluationMode getEvaluationMode()
          Indicates the evaluation mode that I support.
 boolean isReportSuccesses()
          Queries whether successful constraint evaluations are reported, in addition to validation problems.
 void putClientData(java.lang.String key, java.lang.Object data)
          Makes the specified named particle of information available to listeners who will receiver validation events from this validator.
 void setReportSuccesses(boolean reportSuccesses)
          Indicates whether successful constraint evaluations are to be reported, in addition to validation problems.
 org.eclipse.core.runtime.IStatus validate(java.util.Collection objects)
          Validates multiple objects, all in the same validation context.
 org.eclipse.core.runtime.IStatus validate(java.lang.Object object)
          Validates an object.
 

Method Detail

getEvaluationMode

public EvaluationMode 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

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

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

setReportSuccesses

public 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

public void putClientData(java.lang.String key,
                          java.lang.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

public java.lang.Object getClientData(java.lang.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:
IValidator.putClientData(String, Object)

validate

public org.eclipse.core.runtime.IStatus validate(java.lang.Object 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:
java.lang.ClassCastException - if the object is not of the correct type for this validator

validate

public org.eclipse.core.runtime.IStatus validate(java.util.Collection objects)
Validates multiple objects, all in the same validation context. This method is preferable to repeated invocations of IValidator.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:
java.lang.ClassCastException - if any of the objects is not of the correct type for this validator
See Also:
IValidator.validate(Object)

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