    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
    015package org.apache.tapestry5.services;
    016
    017import 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 */
    022public 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}