    001    // Copyright 2006, 2007, 2008 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;
    016
    017    import org.apache.tapestry5.EventConstants;
    018    import org.apache.tapestry5.runtime.Component;
    019
    020    /**
    021     * Used by classes that need to retrieve a component by its complete id, or a page by its logical page name or root
    022     * component class. The complete id is the logical name of the containing page, a colon, and the nested component id. It
    023     * may also just be the page name (for the root component of a page).
    024     */
    025    public interface ComponentSource
    026    {
    027        /**
    028         * Gets a component by its {@linkplain org.apache.tapestry5.ComponentResourcesCommon#getCompleteId() complete id}.
    029         * If the component id is for a mixin, then the mixin attached to the component will be returned. A mixin's complete
    030         * id is its container's complete id, suffixed with "$" and the mixin's id (its simple class name).
    031         *
    032         * @param completeId
    033         *            complete component id (case insensitive)
    034         * @return the component
    035         * @throws IllegalArgumentException
    036         *             if the component can not be found
    037         * @see org.apache.tapestry5.ComponentResourcesCommon#getCompleteId()
    038         */
    039        Component getComponent(String completeId);
    040
    041        /**
    042         * Returns the page identified by its logical page name. A logical page name is the short form of a page name often
    043         * emebedded into URLs.
    044         *
    045         * @param pageName
    046         *            the logical page name
    047         * @return the corresponding page's root component
    048         * @throws IllegalArgumentException
    049         *             if the page can not be found
    050         */
    051        Component getPage(String pageName);
    052
    053        /**
    054         * A convienience for obtaining a page instance via a class instance. This is provided so as to be refactoring
    055         * safe. The pageClass is simply converted to a class name and this is used to locate a page instance.
    056         *
    057         * @param pageClass
    058         *            used to locate the page instance
    059         * @return the page instance
    060         */
    061        Component getPage(Class pageClass);
    062
    063        /**
    064         * Returns the <em>active page</em>, as defined by {@link RequestGlobals#getActivePageName()}. This is the primary
    065         * page for handling the current request, the page which will be {@linkplain EventConstants#ACTIVATE activated} for
    066         * the request.
    067         * The identity of the active page is not known until the correct {@link Dispatcher} determines this.
    068         *
    069         * @return the active page, or null if no active page is yet identified
    070         * @since 5.2.0
    071         */
    072        Component getActivePage();
    073    }