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    }