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