org.netbeans.validation.api.ui
Class ValidationGroup

java.lang.Object
  extended by org.netbeans.validation.api.ui.ValidationGroup

public final class ValidationGroup
extends java.lang.Object

A group which holds validators that run against components. The group is passed an instance of ValidationUI in its constructor. This is typically something that is able to show the user that there is a problem in some way, possibly enabling and disabling a dialog's OK button or similar.

There are two main reasons validation groups exist:

A validation group is typically associated with a single panel. For components this library supports out-of-the-box such as JTextFields or JComboBoxes, simply call one of the add() methods with your component and validators. For validating your own components or ones this class doesn't have methods for, you implement and add ValidationListeners.

The contract of how a validation group works is as follows:

Validator Ordering

For the methods which take multiple validators or multiple enum constants from the Validators class, order is important. Generally it is best to pass validators in order of how specific they are - for example, if you are validating a URL you would likely pass

 group.add(f, Validators.REQUIRE_NON_EMPTY_STRING,
          Validators.NO_WHITESPACE,
          Validators.URL_MUST_BE_VALID);
 
so that the most general check is done first (if the string is empty or not); the most specific test, which will actually try to construct a URL object and report any MalformedURLException should be last.

Validators for custom components can be added to the group by implementing ValidationListener over a listener you attach to the component in question, by calling add(ValidationListener).

Note: All methods on this class must be called from the AWT Event Dispatch thread, or assertion errors will be thrown. Manipulating components on other threads is not safe.

Swing documents are type-safe, and can be modified from other threads. In the case that a text component validator receives an event on another thread, validation will be scheduled for later, on the event thread.

Author:
Tim Boudreau

Method Summary
Modifier and Type Method and Description
 void add(javax.swing.AbstractButton[] buttons, Validator<javax.swing.ButtonModel[]> validator)
          Add a set of button models, e.g.
 void add(javax.swing.ButtonModel[] buttons, Validator<javax.swing.ButtonModel[]> validator)
          Add a set of button models, e.g.
 void add(javax.swing.JComboBox box, ValidationStrategy strategy, Validator<javax.swing.ComboBoxModel> validator)
          Add a combo box using the passed validation strategy and validator
 void add(javax.swing.JComboBox box, ValidationStrategy strategy, Validator<java.lang.String>... builtIns)
          Add a combo box to be validated with the passed validation strategy using the passed validators
 void add(javax.swing.JComboBox box, Validator<javax.swing.ComboBoxModel> validator)
          Add a combo box to be validated with ValidationStrategy.DEFAULT using the passed validator
 void add(javax.swing.JComboBox box, Validator<java.lang.String>... builtIns)
          Add a combo box to be validated with ValidationStrategy.DEFAULT using the passed validators
 void add(javax.swing.text.JTextComponent comp, ValidationStrategy strategy, Validator<javax.swing.text.Document> validator)
          Add a text component to be validated with ValidationStrategy.DEFAULT using the passed validator
 void add(javax.swing.text.JTextComponent comp, ValidationStrategy strategy, Validator<java.lang.String>... builtIns)
          Add a text control to be validated with the passed validation strategy using the passed validators
 void add(javax.swing.text.JTextComponent comp, Validator<javax.swing.text.Document> validator)
          Add a text component to be validated with ValidationStrategy.DEFAULT using the passed validator
 void add(javax.swing.text.JTextComponent comp, Validator<java.lang.String>... builtIns)
          Add a text component to be validated with ValidationStrategy.DEFAULT using the passed validators
 void add(ValidationListener listener)
          Add a validation listener.
 void addUI(ValidationUI ui)
          Add a UI which should be called on validation of this group or any components within it.
 void addValidationGroup(ValidationGroup group, boolean useUI)
          Add a validation group whose components should be validated as a part of this group.
static ValidationGroup create(ValidationUI... ui)
          Create a new ValidationGroup.
 javax.swing.JLabel createProblemLabel()
          Create a label which will show the current problem if any, which can be added to a panel that uses validation
 void modifyComponents(java.lang.Runnable run)
          Disable validation and invoke a runnable.
 void removeUI(ValidationUI ui)
          Remove a delegate UI which is being controlled by this validation group.
 void removeValidationGroup(ValidationGroup group)
          Remove a child validation group from this one.
 void setComponentDecorator(ComponentDecorator decorator)
          Set the component decorator used modify components appearance to show that there is a problem with a component's content.
 Problem validateAll()
          Validate all components in this group, updating the UI with a new problem as necessary.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

setComponentDecorator

public void setComponentDecorator(ComponentDecorator decorator)
Set the component decorator used modify components appearance to show that there is a problem with a component's content.

Parameters:
decorator - A decorator. May not be null.

validateAll

public Problem validateAll()
Validate all components in this group, updating the UI with a new problem as necessary. Generally the validation framework handles validation; however you are using custom validators that rely on outside state, this method can be used to manually force validation.

Returns:
A problem, if any

modifyComponents

public final void modifyComponents(java.lang.Runnable run)
Disable validation and invoke a runnable. This method is useful in UIs where a change in one component can trigger changes in another component, and you do not want validation to be triggered because a component was programmatically updated.

For example, say you have a dialog that lets you create a new Servlet source file. As the user types the servlet name, web.xml entries are updated to match, and these are also in fields in the same dialog. Since the updated web.xml entries are being programmatically (and presumably correctly) generated, those changes should not trigger a useless validation run. Wrap such generation code in a Runnable and pass it to this method when making programmatic changes to the contents of the UI.

The runnable is run synchronously, but no changes made to components while the runnable is running will trigger validation.

When the last runnable exits, validateAll(null) will be called to run validation against the entire newly updated UI.

This method is reentrant - a call to updateComponents can trigger another call to updateComponents without triggering multiple calls to validateAll() on each Runnable's exit.

Parameters:
run - A runnable which makes changes to the contents of one or more components in the UI which should not trigger validation

create

public static ValidationGroup create(ValidationUI... ui)
Create a new ValidationGroup.

Parameters:
ui - The user interface
Returns:
A new ValidationGroup

add

public void add(javax.swing.ButtonModel[] buttons,
                Validator<javax.swing.ButtonModel[]> validator)
Add a set of button models, e.g. radio buttons in a radio button group

Parameters:
buttons - The button models
validator - A validator

add

public final void add(javax.swing.AbstractButton[] buttons,
                      Validator<javax.swing.ButtonModel[]> validator)
Add a set of button models, e.g. radio buttons in a radio button group

Parameters:
buttons - The button models
validator - A validator

createProblemLabel

public final javax.swing.JLabel createProblemLabel()
Create a label which will show the current problem if any, which can be added to a panel that uses validation

Returns:
A JLabel

add

public void add(javax.swing.JComboBox box,
                ValidationStrategy strategy,
                Validator<javax.swing.ComboBoxModel> validator)
Add a combo box using the passed validation strategy and validator

Parameters:
box - a combo box
strategy - the validation strategy that determines when validation should run
validator - A validator for combo box models (e.g. from Converters.convert() to use String validators in combo boxes)

add

public void add(javax.swing.text.JTextComponent comp,
                ValidationStrategy strategy,
                Validator<javax.swing.text.Document> validator)
Add a text component to be validated with ValidationStrategy.DEFAULT using the passed validator

Parameters:
comp - A text component such as a JTextField
validator - A validator

add

public final void add(javax.swing.JComboBox box,
                      ValidationStrategy strategy,
                      Validator<java.lang.String>... builtIns)
Add a combo box to be validated with the passed validation strategy using the passed validators

Parameters:
box - A combo box component
builtIns - One or more of the enums from the Validators class which provide standard validation of many things

add

public final void add(javax.swing.text.JTextComponent comp,
                      ValidationStrategy strategy,
                      Validator<java.lang.String>... builtIns)
Add a text control to be validated with the passed validation strategy using the passed validators

Parameters:
comp - A text control such as a JTextField
builtIns - One or more of the enums from the Validators class which provide standard validation of many things

add

public final void add(javax.swing.JComboBox box,
                      Validator<java.lang.String>... builtIns)
Add a combo box to be validated with ValidationStrategy.DEFAULT using the passed validators

Parameters:
box - A combo box component
builtIns - One or more of the enums from the Validators class which provide standard validation of many things

add

public final void add(javax.swing.JComboBox box,
                      Validator<javax.swing.ComboBoxModel> validator)
Add a combo box to be validated with ValidationStrategy.DEFAULT using the passed validator

Parameters:
box - A text component such as a JTextField
validator - A validator

add

public final void add(javax.swing.text.JTextComponent comp,
                      Validator<java.lang.String>... builtIns)
Add a text component to be validated with ValidationStrategy.DEFAULT using the passed validators

Parameters:
comp - A text component such as a JTextField
builtIns - One or more of the enums from the Validators class which provide standard validation of many things

add

public final void add(javax.swing.text.JTextComponent comp,
                      Validator<javax.swing.text.Document> validator)
Add a text component to be validated with ValidationStrategy.DEFAULT using the passed validator

Parameters:
comp - A text component such as a JTextField
validator - A validator

add

public void add(ValidationListener listener)
Add a validation listener. To validate custom components, implement ValidationListener and attach it as a listener to the component, calling ValidationListener.validate() on events that should trigger validation, and add it to the group.


addValidationGroup

public final void addValidationGroup(ValidationGroup group,
                                     boolean useUI)
Add a validation group whose components should be validated as a part of this group. This is useful in the case that you have a panel with its own validation group, and want to embed it another panel that also wants to do its own validation.

Whenever there is a change in one of the child ValidationGroupc's components, it will drive the UI(s) belonging to this group, as well as (optionally) its own.

This technique is mostly useful in the case of things like abstract customizer dialogs, where you have a ValidationUI to control the OK button, but you don't actually anything about the component provided as a customizer. This method makes it possible for a parent component (such as our customizer) to be affected by validation in a child component.

If you are not composing together multiple panels which each have their own validation code, ignore this method.

Parameters:
group - The validation group
useUI - If true, the other validation group's UI should continue to be updated

removeValidationGroup

public final void removeValidationGroup(ValidationGroup group)
Remove a child validation group from this one. In the case of composing together panels, each of which has its own validation group, this method is useful if the child panel changes on the fly.

Once removed, the child validation group reverts to interacting only with its own UI, and validation running in it will not affect the UI of this ValidationGroup.

Parameters:
group -

addUI

public final void addUI(ValidationUI ui)
Add a UI which should be called on validation of this group or any components within it.

This is useful in the case that you have multiple components which are provided separately and each want to respond to validation problems (for example, one UI controlling a dialog's OK button, another controlling display of error text.

Parameters:
ui - An implementation of ValidationUI

removeUI

public final void removeUI(ValidationUI ui)
Remove a delegate UI which is being controlled by this validation group.

Parameters:
ui - The UI