001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.resource.loader;
018
019import java.util.Locale;
020
021import org.apache.wicket.Component;
022
023
024/**
025 * The string resource loader interface allows a strategy pattern to be applied to the loading of
026 * resource strings for an application. The loader (or chain of loaders) that are used is configured
027 * via the application settings.
028 * <p>
029 * Each particular implementation of this interface may define its own mechanism for searching for
030 * resources. Please see the documents for each particular implementation to determine its behavior
031 * and to see how it can be configured.
032 * <p>
033 * It is important to note that if a resource is not found by a particular loader than the loader
034 * should return <code>null</code> rather than throw an exception. The reason for this is that
035 * loaders can be arranged in a chain and it would be very inefficient for loaders earlier in the
036 * chain to throw exceptions that must be caught and handled each time until the correct loader in
037 * the chain is reached.
038 * 
039 * @see org.apache.wicket.settings.ResourceSettings
040 * 
041 * @author Chris Turner
042 * @author Juergen Donnerstag
043 */
044public interface IStringResourceLoader
045{
046        /**
047         * Get the string resource for the given combination of component class, resource key, locale
048         * and style. The component class provided is used to allow implementation of component specific
049         * resource loading (e.g. per page or per reusable component). The key should be a String
050         * containing a lookup key into a resource bundle. The locale should contain the locale of the
051         * current operation so that the appropriate set of resources can be selected. The style allows
052         * the set of resources to select to be varied by skin/brand.
053         * 
054         * @param clazz
055         *            The class to get the string resource for
056         * @param key
057         *            The key should be a String containing a lookup key into a resource bundle
058         * @param locale
059         *            The locale should contain the locale of the current operation so that the
060         *            appropriate set of resources can be selected
061         * @param style
062         *            The style identifying the resource set to select the strings from (see
063         *            {@link org.apache.wicket.Session})
064         * @param variation
065         *            The components variation (of the style)
066         * @return The string resource value or null if the resource could not be loaded by this loader
067         */
068        String loadStringResource(Class<?> clazz, String key, Locale locale, String style,
069                String variation);
070
071        /**
072         * Get the string resource for the given combination of component, resource key, locale and
073         * style. The component provided is used to allow implementation of component specific resource
074         * loading (e.g. per page or per reusable component). The key should be a String containing a
075         * lookup key into a resource bundle. The Locale and the style will be taken from the Component
076         * provided.
077         * 
078         * @param component
079         *            The component to get the string resource for
080         * @param key
081         *            The key should be a String containing a lookup key into a resource bundle
082         * @param locale
083         *            Will be preset with the appropriate value. You shall ignore the component's
084         *            locale.
085         * @param style
086         *            Will be preset with the appropriate value. You shall ignore the component's style.
087         * @param variation
088         *            Will be preset with the appropriate value. You shall ignore the component's
089         *            variation.
090         * @return The string resource value or null if the resource could not be loaded by this loader
091         */
092        String loadStringResource(Component component, String key, Locale locale, String style,
093                String variation);
094}