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    }