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    
015    package org.apache.tapestry.services;
016    
017    import java.util.Locale;
018    
019    import org.apache.tapestry.IComponent;
020    import 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     */
032    public 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    }