    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    }