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}