    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
    015    package org.apache.tapestry5.services.messages;
    016
    017    import org.apache.tapestry5.ioc.Messages;
    018    import org.apache.tapestry5.ioc.Resource;
    019    import org.apache.tapestry5.ioc.annotations.NotLazy;
    020    import org.apache.tapestry5.ioc.annotations.UsesOrderedConfiguration;
    021    import org.apache.tapestry5.model.ComponentModel;
    022    import org.apache.tapestry5.services.InvalidationEventHub;
    023    import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
    024
    025    import 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)
    036    public 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    }