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;

}