jakarta.faces.validator.Validator Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.faces.validator;
import java.util.EventListener;
import jakarta.faces.component.UIComponent;
import jakarta.faces.context.FacesContext;
/**
*
* A Validator implementation is a class that can perform validation
* (correctness checks) on a {@link jakarta.faces.component.EditableValueHolder}. Zero or more Validators
* can be associated with each {@link jakarta.faces.component.EditableValueHolder} in the view, and are called during
* the Process Validations phase of the request processing lifecycle.
*
*
*
* Individual {@link Validator}s should examine the value and component that they are passed, and throw a
* {@link ValidatorException} containing a {@link jakarta.faces.application.FacesMessage}, documenting any failures to
* conform to the required rules.
*
*
* For maximum generality, {@link Validator} instances may be configurable based on properties of the {@link Validator}
* implementation class. For example, a range check {@link Validator} might support configuration of the minimum and
* maximum values to be used.
*
*
*
* {@link Validator} implementations must have a zero-arguments public constructor. In addition, if the
* {@link Validator} class wishes to have configuration property values saved and restored with the view, the
* implementation must also implement {@link jakarta.faces.component.StateHolder}.
*
*
*
* If the class implementing Validator has a {@link jakarta.faces.application.ResourceDependency}
* annotation, the action described in ResourceDependency must be taken when
* {@link jakarta.faces.component.EditableValueHolder#addValidator} is called. If the class implementing
* Validator has a {@link jakarta.faces.application.ResourceDependencies} annotation, the action described
* in ResourceDependencies must be taken when
* {@link jakarta.faces.component.EditableValueHolder#addValidator} is called.
*
*
* @param The generic type of object value to validate.
*/
public interface Validator extends EventListener {
/**
*
* Perform the correctness checks implemented by this {@link Validator}
* against the specified {@link UIComponent}. If any violations are found, a {@link ValidatorException} will be thrown
* containing the {@link jakarta.faces.application.FacesMessage} describing the failure.
*
*
*
*
* For a validator to be fully compliant with Version 2 and later of the specification, it must not fail validation on
* null or empty values unless it is specifically intended to address null or empty values. An
* application-wide <context-param> is provided to allow validators designed for Jakarta Faces
* 1.2 to work with Jakarta Faces 2 and later. The jakarta.faces.VALIDATE_EMPTY_FIELDS
* <context-param> must be set to false to enable this backwards compatibility behavior.
*
*
*
*
* @param context FacesContext for the request we are processing
* @param component UIComponent we are checking for correctness
* @param value the value to validate
* @throws ValidatorException if validation fails
* @throws NullPointerException if context or component is null
*/
void validate(FacesContext context, UIComponent component, T value) throws ValidatorException;
}