jakarta.faces.validator.Validator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.faces Show documentation
EE4J Compatible Implementation for Jakarta Faces API
The newest version!
/*
 * 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;

}