001    //  Copyright 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.services;
016    
017    import org.apache.tapestry5.ComponentResources;
018    import org.apache.tapestry5.Field;
019    import org.apache.tapestry5.FieldTranslator;
020    import org.apache.tapestry5.Translator;
021    import org.apache.tapestry5.ioc.AnnotationProvider;
022    import org.apache.tapestry5.ioc.Messages;
023    
024    import java.util.Locale;
025    
026    /**
027     * For a particular field, generates the default {@link org.apache.tapestry5.FieldTranslator} for the field.
028     */
029    public interface FieldTranslatorSource
030    {
031        /**
032         * Common shorthand for {@link #createDefaultTranslator(org.apache.tapestry5.Field, String,
033         * org.apache.tapestry5.ioc.Messages, java.util.Locale, Class, org.apache.tapestry5.ioc.AnnotationProvider)}.
034         *
035         * @param resources     of component who owns the parameter
036         * @param parameterName name of parameter used to determine the property type
037         * @return field translator, or null
038         */
039        FieldTranslator createDefaultTranslator(ComponentResources resources, String parameterName);
040    
041        /**
042         * Creates a {@link org.apache.tapestry5.FieldTranslator} for the given property, or returns null if one can't be
043         * constructed. The return value is null if the property type is not known, or if there is no {@link
044         * org.apache.tapestry5.Translator} available from the {@link org.apache.tapestry5.services.TranslatorSource} that
045         * is appropriate for the property type.
046         *
047         * @param field               for which a translator is needed
048         * @param overrideId          id used when looking in the overrideMessages for a message override
049         * @param overrideMessages    location to look for overriding messages
050         * @param locale              no longer used in 5.3, may be null
051         * @param propertyType        type of property editted by the field, used to select the Translator
052         * @param propertyAnnotations annotations on the property (not currently used)
053         * @return the field translator, or null
054         */
055        FieldTranslator createDefaultTranslator(Field field, String overrideId, Messages overrideMessages, Locale locale,
056                                                Class propertyType, AnnotationProvider propertyAnnotations);
057    
058        /**
059         * Wraps a {@link org.apache.tapestry5.Translator} as a FieldTranslator.
060         * @param locale no longer used in 5.3, may be null
061         */
062        FieldTranslator createTranslator(Field field, String overrideId, Messages overrideMessages, Locale locale,
063                                         Translator translator);
064    
065        /**
066         * Creates a translator (used by the {@link org.apache.tapestry5.BindingConstants#TRANSLATE translate: binding
067         * prefix}).
068         */
069        FieldTranslator createTranslator(ComponentResources componentResources, String translatorName);
070    }