maint-5-2/tapestry-core/src/main/java/org/apache/tapestry5/FieldValidationSupport.java

// Copyright 2007, 2008 The Apache Software Foundation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package org.apache.tapestry5;

/**
 * Services to help with field {@linkplain org.apache.tapestry5.Validator validation} and {@linkplain
 * org.apache.tapestry5.Translator translation}. This service encapsulates the logic that mixes normal
 * configured/declared validation/translation with events triggered on the component.
 */
public interface FieldValidationSupport
{
    /**
     * A wrapper around {@link org.apache.tapestry5.Translator#toClient(Object)} that first fires a "toclient" event on
     * the component to see if it can perform the conversion. If the value is null, then no event is fired and the
     * translator is <em>not</em> invoked, the return value is simply null.
     *
     * @param value              to be converted to a client-side string, which may be null
     * @param componentResources used to fire events on the component
     * @param translator         used if the component does not provide a non-null value
     * @param nullFieldStrategy  used to convert a null server side value to an appropriate client side value
     * @return the translated value  or null if the value is null
     * @see org.apache.tapestry5.Translator#toClient(Object)
     */
    String toClient(Object value, ComponentResources componentResources, FieldTranslator<Object> translator,
                    NullFieldStrategy nullFieldStrategy);

    /**
     * A wrapper around {@link Translator#parseClient(Field, String, String)}. First a "parseclient" event is fired; the
     * translator is only invoked if that returns null (typically because there is no event handler method for the
     * event).
     *
     * @param clientValue        the value provided by the client (not null)
     * @param componentResources used to trigger events
     * @param translator         translator that will do the work if the component event returns null
     * @param nullFieldStrategy  used to convert null/blank values from client into non-null server side values
     * @return the input parsed to an object
     * @throws org.apache.tapestry5.ValidationException
     *          if the value can't be parsed
     * @see Translator#parseClient(Field, String, String)
     */
    Object parseClient(String clientValue, ComponentResources componentResources, FieldTranslator<Object> translator,
                       NullFieldStrategy nullFieldStrategy)
            throws ValidationException;

    /**
     * Performs validation on a parsed value from the client.  Normal validations occur first, then a "validate" event
     * is triggered on the component.
     *
     * @param value              parsed value from the client, possibly null
     * @param componentResources used to trigger events
     * @param validator          performs normal validations
     * @throws ValidationException if the value is not valid
     * @see org.apache.tapestry5.Validator#validate(Field, Object, org.apache.tapestry5.ioc.MessageFormatter, Object)
     */
    void validate(Object value, ComponentResources componentResources, FieldValidator validator)
            throws ValidationException;
}