001// Copyright 2005 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.tapestry.services;
016
017import java.util.Locale;
018
019import org.apache.tapestry.IComponent;
020import org.apache.tapestry.INamespace;
021
022/**
023 * Enapsulates the logic for searching for component meta-data. Deployed as service
024 * tapestry.props.ComponentPropertySource.
025 * <p>
026 * TODO: Adjust name, since it now provides access to namespace properties as well as component
027 * properties.
028 * 
029 * @author Howard M. Lewis Ship
030 * @since 4.0
031 */
032public interface ComponentPropertySource
033{
034    /**
035     * Returns the property value for a particular named meta-data property of the component. The
036     * search order is:
037     * <ul>
038     * <li>The component's specification</li>
039     * <li>The specification of the application (or the library containing the component).</li>
040     * <li>The chain of global property sources.</li>
041     * </ul>
042     * 
043     * @return the value of the given key, or null if not found.
044     */
045
046    public String getComponentProperty(IComponent component, String propertyName);
047
048    /**
049     * Like {@link #getComponentProperty(IComponent, String)}, but the property name will be
050     * localized to the component's current locale (determined from its page). Localizing the
051     * property name means that a suffix may be appended to it. If the fully localized name is not
052     * found, then the locale is generalized (i.e., from "en_UK" to "en" to nothing) until a match
053     * is found.
054     * 
055     * @return the value of the given property name, or null if not found.
056     */
057    public String getLocalizedComponentProperty(IComponent component, Locale locale,
058            String propertyName);
059
060    /**
061     * Returns the property value for a particular named meta-data property of the namespace. The
062     * search order is:
063     * <ul>
064     * <li>The library or application specification for the namespace.</li>
065     * <li>The chain of global property sources.</li>
066     * </ul>
067     * 
068     * @return the value of the given key, or null if not found.
069     */
070
071    public String getNamespaceProperty(INamespace namespace, String propertyName);
072
073    /**
074     * As with {@link #getLocalizedComponentProperty(IComponent, Locale, String)}, but with a
075     * {@link INamespace}.
076     */
077
078    public String getLocalizedNamespaceProperty(INamespace namespace, Locale locale,
079            String propertyName);
080}