    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
    015    package 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     */
    022    public 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    }