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    
015    package org.apache.tapestry5.services;
016    
017    import org.apache.tapestry5.*;
018    
019    /**
020     * A service that can be injected into a component to provide common defaults for various types of parameters.
021     */
022    public interface ComponentDefaultProvider
023    {
024        /**
025         * Computes the default label for the component (which will generally be a {@link Field}).
026         *
027         * @param resources
028         * @return the label, either extracted from the component's container's message catalog, or derived from the
029         *         component's {@link ComponentResourcesCommon#getId()}.
030         */
031        String defaultLabel(ComponentResources resources);
032    
033        /**
034         * Checks to see if the container of the component (identified by its resources) contains a property matching the
035         * component's id. If so, a binding for that property is returned. This is usually the default for a {@link Field}'s
036         * value parameter (or equivalent).
037         *
038         * @param parameterName the name of the parameter
039         * @param resources     the resources of the component for which a binding is needed
040         * @return the binding, or null if the container does not have a matching property
041         */
042        Binding defaultBinding(String parameterName, ComponentResources resources);
043    
044        /**
045         * Gets or creates a value encoder based on the <em>type</em> of the named parameter.  ValueEncoders are cached
046         * based on type.
047         *
048         * @param parameterName the name of the parameter whose type is used to locate a {@link
049         *                      org.apache.tapestry5.services.ValueEncoderFactory}
050         * @param resources     the resources of the component, from which parameter and its type are extracted
051         * @return the value encoder, or null if the type of the parameter is not known
052         */
053        ValueEncoder defaultValueEncoder(String parameterName, ComponentResources resources);
054    
055        /**
056         * Provides a translator based on the bound parameter type, if possible.
057         *
058         * @param parameterName
059         * @param resources
060         * @return the translator, or null
061         * @deprecated Use {@link #defaultTranslatorBinding(String, org.apache.tapestry5.ComponentResources)} instead
062         */
063        FieldTranslator defaultTranslator(String parameterName, ComponentResources resources);
064    
065        /**
066         * Provides a binding that itself provides the field translator.
067         *
068         * @param parameterName
069         * @param resources
070         * @return binding that provides the {@link org.apache.tapestry5.FieldTranslator}
071         */
072        Binding defaultTranslatorBinding(String parameterName, ComponentResources resources);
073    
074        /**
075         * Provides a validator based on the bound parameter type.  If the property type of the parameter is not known, then
076         * a no-op validator is returned.
077         *
078         * @param parameterName
079         * @param resources
080         * @return the validator, possibly a no-op validator
081         * @deprecated Use {@link #defaultValidatorBinding(String, org.apache.tapestry5.ComponentResources)} instead
082         */
083        FieldValidator defaultValidator(String parameterName, ComponentResources resources);
084    
085        /**
086         * Provides a binding that itself provides the field translator.
087         *
088         * @param parameterName
089         * @param resources
090         * @return binding that provides the {@link org.apache.tapestry5.FieldTranslator}
091         */
092        Binding defaultValidatorBinding(String parameterName, ComponentResources resources);
093    }