001// Copyright 2006, 2008, 2009, 2010, 2011 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.messages;
016
017import org.apache.tapestry5.commons.Messages;
018import org.apache.tapestry5.commons.Resource;
019import org.apache.tapestry5.commons.services.InvalidationEventHub;
020import org.apache.tapestry5.ioc.annotations.NotLazy;
021import org.apache.tapestry5.ioc.annotations.UsesOrderedConfiguration;
022import org.apache.tapestry5.model.ComponentModel;
023import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
024
025import java.util.Locale;
026
027/**
028 * Used to connect a Tapestry component to its message catalog, or to obtain the application catalog (that all
029 * component message catalogs extend from). The application catalog is defined by the collection of {@link Resource}s
030 * contributed to the service. In general, component libraries will contribute a Resource before the "AppCatalog"
031 * resource (representing
032 * the application message catalog, WEB-INF/app.properties) so that the application can override messages of the
033 * component library.
034 */
035@UsesOrderedConfiguration(Resource.class)
036public interface ComponentMessagesSource
037{
038    /**
039     * Used to obtain a {@link Messages} instance for a particular component, within a particular locale. If the
040     * component extends from another component, then its localized properties will merge with its parent's properties
041     * (with the subclass overriding the super class on any conflicts).
042     *
043     * @param componentModel
044     * @param locale
045     * @return the message catalog for the component, in the indicated locale
046     * @deprecated Deprecated in 5.3; use {@link #getMessages(ComponentModel, ComponentResourceSelector)} instead.
047     */
048    Messages getMessages(ComponentModel componentModel, Locale locale);
049
050    /**
051     * Used to obtain a {@link Messages} instance for a particular component, using a particular selector. If the
052     * component extends from another component, then its localized properties will merge with its parent's properties
053     * (with the subclass overriding the super class on any conflicts).
054     *
055     * @param componentModel
056     * @param selector       determined correct version of messages to obtain
057     * @return the message catalog for the component, in the indicated selector
058     * @since 5.3
059     */
060    Messages getMessages(ComponentModel componentModel, ComponentResourceSelector selector);
061
062    /**
063     * Gets the Messages derived from the application's message catalog.
064     *
065     * @since 5.2.0
066     */
067    Messages getApplicationCatalog(Locale locale);
068
069    /**
070     * Returns the event hub that allows listeners to be notified when any underlying message catalog file is changed.
071     *
072     * @since 5.1.0.0
073     */
074    @NotLazy
075    InvalidationEventHub getInvalidationEventHub();
076}