001    // Copyright 2006, 2008, 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.internal.services;
016    
017    import org.apache.tapestry5.internal.parser.ComponentTemplate;
018    import org.apache.tapestry5.model.ComponentModel;
019    import org.apache.tapestry5.services.InvalidationEventHub;
020    import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
021    
022    /**
023     * Provides access to cached {@link org.apache.tapestry5.internal.parser.ComponentTemplate}s. The source acts as a
024     * invalidation event hub, and will broadcast invalidation events when any loaded template resource changes. The
025     * listener for these invalidation events is the page source, which stores cached page instances.
026     * <p/>
027     * Any search for a template will end with success (a non-null template), but the template returned may be the
028     * {@link ComponentTemplate#isMissing() missing template}.
029     */
030    public interface ComponentTemplateSource
031    {
032        /**
033         * Provides access to a template. The template will be parsed as necessary. If no template for the exact component
034         * is found, then the template for the component's parent is returned. In this way, it is possible for a component
035         * to extend the behavior of its super-class without duplicating the super-class component's template.
036         * <p/>
037         * In some cases, the empty template will be returned.
038         * 
039         * @param componentModel
040         *            model for the component whose template is to be accessed
041         * @param selector
042         *            defines locale and other information needed to locate template
043         * @return the cached template instance
044         */
045        ComponentTemplate getTemplate(ComponentModel componentModel, ComponentResourceSelector selector);
046    
047        /**
048         * Event hub used to notify listeners that underlying component template files have changed.
049         * 
050         * @see org.apache.tapestry5.services.ComponentTemplates
051         * @since 5.1.0.0
052         */
053        InvalidationEventHub getInvalidationEventHub();
054    }