RSE Validators API
Throughout an eclipse UI there are times when we need to validate what the user has typed in. Validators
offer a way to encapsulate the error checking for a particular domain, so it can be re-used wherever the user
is prompted for this. This includes dialogs, property pages, preference pages, wizard pages and viewer
cells. Eclipse's JFace offers two interfaces for this, one for viewer cells and one for the rest. In RSE,
there is a single interface combining the requirements of both, so you can author a single validator that is
re-usable anywhere. Further, the RSE validator interface and sub-interfaces force additional information to be
supplied to enhance re-use, such as the maximum length, which can be used to set the text limit for a text field.
RSE Validator Interfaces
All RSE validator interfaces and classes are in package
org.eclipse.rse.ui.validators
.
ISystemValidator Interface
The primary validator interface is
ISystemValidator
, which is extends org.eclipse.jface.dialogs.IInputValidator
and org.eclipse.jface.viewers.ICellEditorValidator. Both parent interfaces define an isValid method,
but the former takes a String while the latter takes an Object. They both return a String which is the error message if an
error was detected, or null if no error detected. The ISystemValidator interface adds the following additional methods:
| Method |
Description |
|
public int
getMaximumNameLength()
|
Returns the maximum length allowed for this text. Can be used to set text limit of text widgets. |
|
public SystemMessage
getSystemMessage()
|
If isValid returns false, this returns a SystemMessage object that offers richer message support than just a string.
Return null if you don't support
SystemMessages
.
Callers don't need to use this if they use
validate(String)
instead of isValid(String). |
|
public SystemMessage
validate(String text)
|
An alternative to isValid if your validator does support SystemMessage objects versus simple strings for error messages. |
ISystemValidatorUniqueString Interface
Often our validation requires checking that the given text is unique, in some given list of existing things, like names say. To facilitate
this, there is an interface
ISystemValidatorUniqueString
, which extends ISystemValidator and adds some additional
methods required for uniqueness validation:
If you desire to create a unique string validator, you probably will start by subclassing
ValidatorUniqueString
.
IValidatorRemoteSelection Interface
The third validator interface is
IValidatorRemoteSelection
, which is specifically intended to be used
in the remote resource selection dialogs supplied by the RSE. It allows you to decide when to enable the OK button, based on what
is selected. It contains only the following method:
public SystemMessage
isValid(SystemConnection selectedConnection, Object[] selectedObjects, ISystemRemoteElementAdapter[] remoteAdaptersForSelectedObject);
You typically won't implement this interface directly, but rather sublcass ValidatorRemoteSelection.
Validator Samples
RSE-Supplied Validators
You may be able to avoid creating a new validator if you find that RSE has already supplied one you need. Or, you may find it
appropriate to simply subclass one of these RSE-supplied validators. All of them are designed to be either used as-is, or configured
via setter calls, or subclassed, whichever is most convenient.
All of these validators support rich
SystemMessage
objects, versus just simple strings for the error message. When used with the
RSE dialog, property page or wizard page classes, you should call
validate(String)
and call
setErrorMessage
with the result. When used
in other places you should use
isValid(String)
as it returns just the first-level text of the system message.
