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}