# 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:

Method | Description
--- | ---
`public void setCaseSensitive(boolean caseSensitive)` | Specifies whether the test for an existing string should consider case or not.
`public void setExistingNamesList(String[] existingList)` | Sets the existing list to test against, as an array.
`public void setExistingNamesList(Vector existingList)` | Sets the existing list to test against, as a vector of Strings.
`public String[] getExistingNamesList()` | Returns the existing list that is used to test against.

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

- Sample 1
- Sample 2
- Sample 3
- Sample 4

## 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.

Validator Class | Description
--- | ---
`ValidatorCompileCommandLabel` | Validates the label for a compile command in the RSE.
`ValidatorConnectionName` | Validates the name of a connection in the RSE.
`ValidatorFileName` | Validates the name of a file in eclipse.
`ValidatorFilterName` | Validates the name of a filter in the RSE.
`ValidatorFilterPoolName` | Validates the name of a filter pool in the RSE.
`ValidatorFilterString` | Validates the contents of a filter string in the RSE.
`ValidatorFolderName` | Validates the name of a folder in eclipse.
`ValidatorIntegerInput` | Validates the given string is a valid integer.
`ValidatorIntegerRangeInput` | Validates the given string is a valid integer within a given range.
`ValidatorLongInput` | Validates the given string is a valid long integer.
`ValidatorLongRangeInput` | Validates the given string is a valid long integer within a given range.
`ValidatorPathName` | Validates the given string is a valid folder path in eclipse.
`ValidatorPortInput` | Validates the given string is a valid TCP/IP port number.
`ValidatorProfileName` | Validates the name of a system profile in the RSE.
`ValidatorRemoteSelection` | This is a very special case abstract base class, for validators that decide the enablement of the OK button in the RSE-supplied remote resource selection dialogs.
`ValidatorSourceType` | A validator for source types, such as a file type or "*.java". It is intended to be subclassed.
`ValidatorSpecialChar` | A base class for validators that need to ensure the given string doesn't contain certain characters.
`ValidatorSystemName` | A name validator, to be used when the name being prompted for must follow Java identifier rules.
`ValidatorUniqueString` | A base class, or configurable class, to be used for any validation that requires the string to be unique within a given list.
`ValidatorUserActionCommand` | Validates the command of a user defined action in the RSE.
`ValidatorUserActionComment` | Validates the comment of a user defined action in the RSE.
`ValidatorUserActionName` | Validates the name of a user defined action in the RSE.
`ValidatorUserId` | Validates a user ID. Does only basic checking, intended to be subclassed.
`ValidatorUserTypeName` | Validates the name of a named type in the RSE.
`ValidatorUserTypeTypes` | Validates the type list of a named type in the RSE.