    001    //  Copyright 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     * A wrapper around {@link org.apache.tapestry5.Translator} that combines the translator for a specific {@link
    019     * org.apache.tapestry5.Field} and (sometimes) an override of the default validation message (used when an input value
    020     * can't be parsed).
    021     */
    022    public interface FieldTranslator<T>
    023    {
    024        /**
    025         * Returns the type of the server-side value.
    026         *
    027         * @return a type
    028         */
    029        Class<T> getType();
    030
    031        /**
    032         * Invoked after the client-submitted value has been {@link Translator translated} to check that the value conforms
    033         * to expectations (often, in terms of minimum or maximum value). If and only if the value is approved by all
    034         * Validators is the value applied by the field.
    035         *
    036         * @throws ValidationException if the value violates the constraint
    037         */
    038        T parse(String input) throws ValidationException;
    039
    040        /**
    041         * Converts a server-side value to a client-side string. This allows for formatting of the value in a way
    042         * appropriate to the end user.
    043         *
    044         * @param value the server side value (which will not be null)
    045         * @return client-side value to present to the user
    046         * @see Translator#toClient(Object)
    047         */
    048        String toClient(T value);
    049
    050        /**
    051         * Invokes {@link Translator#render(Field, String, MarkupWriter,org.apache.tapestry5.services.FormSupport)}. This is
    052         * called at a point "inside" the tag, so that additional attributes may be added.  In many cases, the underlying
    053         * {@link org.apache.tapestry5.Validator} may write client-side JavaScript to enforce the constraint as well.
    054         *
    055         * @param writer markup writer to direct output to.
    056         * @see org.apache.tapestry5.MarkupWriter#attributes(Object[])
    057         */
    058        void render(MarkupWriter writer);
    059    }