    001    // Copyright 2006, 2008, 2011 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    import org.apache.tapestry5.services.FormSupport;
    018
    019    /**
    020     * Translates between client-side and server-side values. Client-side values are always strings.
    021     *
    022     * @param <T>
    023     * @see org.apache.tapestry5.services.TranslatorSource
    024     * @see org.apache.tapestry5.FieldValidationSupport
    025     * @see org.apache.tapestry5.FieldTranslator
    026     */
    027    public interface Translator<T>
    028    {
    029        /**
    030         * Returns a unique name for the translator. This is used to identify the translator by name, but is also used when
    031         * locating override messages for the translator.
    032         *
    033         * @return unique name for the translator
    034         */
    035        String getName();
    036
    037        /**
    038         * Converts a server-side value to a client-side string. This allows for formatting of the value in a way
    039         * appropriate to the end user. The output client value should be parsable by
    040         * {@link #parseClient(Field, String, String)}.
    041         *
    042         * @param value
    043         *            the server side value (which will not be null)
    044         * @return client-side value to present to the user
    045         */
    046        String toClient(T value);
    047
    048        /**
    049         * Returns the type of the server-side value.
    050         *
    051         * @return a type
    052         */
    053        Class<T> getType();
    054
    055        /**
    056         * Returns the message key, within the application's global message catalog, normally used by this validator. This
    057         * is used to provide the formatted message to {@link #parseClient(Field, String, String)} or
    058         * {@link #render(Field, String, MarkupWriter, org.apache.tapestry5.services.FormSupport)}.
    059         *
    060         * @return a message key
    061         */
    062        String getMessageKey();
    063
    064        /**
    065         * Converts a submitted request value into an appropriate server side value.
    066         *
    067         * @param field
    068         *            for which a value is being parsed
    069         * @param clientValue
    070         *            to convert to a server value; this will not be null, but may be blank
    071         * @param message
    072         *            formatted validation message, either from validation messages, or from an override
    073         * @return equivalent server-side value (possibly null)
    074         * @throws ValidationException
    075         *             if the value can not be parsed
    076         */
    077        T parseClient(Field field, String clientValue, String message) throws ValidationException;
    078
    079        /**
    080         * Hook used by components to allow the validator to contribute additional attributes or (more often) client-side
    081         * JavaScript (via the
    082         * {@link org.apache.tapestry5.services.FormSupport#addValidation(Field, String, String, Object)}).
    083         *
    084         * @param field
    085         *            the field which is currently being rendered
    086         * @param message
    087         *            formatted validation message, either from validation messages, or from an override
    088         * @param writer
    089         *            markup writer, allowing additional attributes to be written into the active element
    090         * @param formSupport
    091         *            used to add JavaScript
    092         */
    093        void render(Field field, String message, MarkupWriter writer, FormSupport formSupport);
    094    }