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