    001// Copyright 2007, 2008 The Apache Software Foundation
    002//
    003// Licensed under the Apache License, Version 2.0 (the "License");
    004// you may not use this file except in compliance with the License.
    005// You may obtain a copy of the License at
    006//
    007//     http://www.apache.org/licenses/LICENSE-2.0
    008//
    009// Unless required by applicable law or agreed to in writing, software
    010// distributed under the License is distributed on an "AS IS" BASIS,
    011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012// See the License for the specific language governing permissions and
    013// limitations under the License.
    014
    015package org.apache.tapestry5;
    016
    017/**
    018 * Services to help with field {@linkplain org.apache.tapestry5.Validator validation} and {@linkplain
    019 * org.apache.tapestry5.Translator translation}. This service encapsulates the logic that mixes normal
    020 * configured/declared validation/translation with events triggered on the component.
    021 */
    022public interface FieldValidationSupport
    023{
    024    /**
    025     * A wrapper around {@link org.apache.tapestry5.Translator#toClient(Object)} that first fires a "toclient" event on
    026     * the component to see if it can perform the conversion. If the value is null, then no event is fired and the
    027     * translator is <em>not</em> invoked, the return value is simply null.
    028     *
    029     * @param value              to be converted to a client-side string, which may be null
    030     * @param componentResources used to fire events on the component
    031     * @param translator         used if the component does not provide a non-null value
    032     * @param nullFieldStrategy  used to convert a null server side value to an appropriate client side value
    033     * @return the translated value  or null if the value is null
    034     * @see org.apache.tapestry5.Translator#toClient(Object)
    035     */
    036    String toClient(Object value, ComponentResources componentResources, FieldTranslator<Object> translator,
    037                    NullFieldStrategy nullFieldStrategy);
    038
    039    /**
    040     * A wrapper around {@link Translator#parseClient(Field, String, String)}. First a "parseclient" event is fired; the
    041     * translator is only invoked if that returns null (typically because there is no event handler method for the
    042     * event).
    043     *
    044     * @param clientValue        the value provided by the client (not null)
    045     * @param componentResources used to trigger events
    046     * @param translator         translator that will do the work if the component event returns null
    047     * @param nullFieldStrategy  used to convert null/blank values from client into non-null server side values
    048     * @return the input parsed to an object
    049     * @throws org.apache.tapestry5.ValidationException
    050     *          if the value can't be parsed
    051     * @see Translator#parseClient(Field, String, String)
    052     */
    053    Object parseClient(String clientValue, ComponentResources componentResources, FieldTranslator<Object> translator,
    054                       NullFieldStrategy nullFieldStrategy)
    055            throws ValidationException;
    056
    057    /**
    058     * Performs validation on a parsed value from the client.  Normal validations occur first, then a "validate" event
    059     * is triggered on the component.
    060     *
    061     * @param value              parsed value from the client, possibly null
    062     * @param componentResources used to trigger events
    063     * @param validator          performs normal validations
    064     * @throws ValidationException if the value is not valid
    065     * @see org.apache.tapestry5.Validator#validate(Field, Object, org.apache.tapestry5.ioc.MessageFormatter, Object)
    066     */
    067    void validate(Object value, ComponentResources componentResources, FieldValidator validator)
    068            throws ValidationException;
    069}