001// Copyright 2006, 2007, 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;
016
017import java.util.List;
018import java.util.Map;
019
020import org.apache.tapestry5.Asset;
021import org.apache.tapestry5.ioc.annotations.UsesConfiguration;
022import org.apache.tapestry5.ioc.services.ClassNameLocator;
023import org.apache.tapestry5.services.transform.ControlledPackageType;
024
025/**
026 * Resolves page names and component types to fully qualified class names. Pages and components may be provided by the
027 * application or inside a <em>mapped package</em>. Page names often appear inside URLs, and component types often
028 * appear in component template (when specifying the type of an embedded component).
029 * <p/>
030 * The service is configured using a collection of {@link LibraryMapping}s. Each mapping maps a prefix, such as "core"
031 * to a root package name, such as "org.apache.tapestry5.corelib". The root package is expected to have sub-packages:
032 * "pages", "components", "mixins" and "base" ("base" is for base classes).
033 * <p/>
034 * The resolver performs a search of the classpath (via {@link ClassNameLocator}), to build up a set of case-insensitive
035 * maps from logical page name, component type, or mixin type to fully qualified class name.
036 * <p/>
037 * Certain ambiguities occur if mapped packages overlap, either in terms of the the prefixes or the package names. Keep
038 * things clearly separate to avoid lookup problems.
039 */
040@UsesConfiguration(LibraryMapping.class)
041public interface ComponentClassResolver
042{
043    /**
044     * Converts a logical page name (such as might be encoded into a URL) into a fully qualified class name. The case of
045     * the page name is irrelevant.
046     * 
047     * @param pageName
048     *            page name
049     * @return fully qualified class name for the page
050     * @throws org.apache.tapestry5.ioc.util.UnknownValueException
051     *             if the name does not match a known page class
052     */
053    String resolvePageNameToClassName(String pageName);
054
055    /**
056     * For a particular path, determines if the path is a logical page name. The check is case insensitive.
057     * 
058     * @param pageName
059     *            potential logical page name
060     * @return true if the page name is valid
061     */
062    boolean isPageName(String pageName);
063
064    /**
065     * Returns a list of all page names, in sorted order.
066     */
067    List<String> getPageNames();
068
069    /**
070     * Converts a fully qualified page class name into a page name (often, for inclusion as part of the URI). This value
071     * may later be passed to {@link #resolvePageNameToClassName(String)}.
072     * 
073     * @param pageClassName
074     *            fully qualified name of a page class
075     * @return equivalent logical page name
076     * @throws IllegalArgumentException
077     *             if the name can not be resolved
078     */
079    String resolvePageClassNameToPageName(String pageClassName);
080
081    /**
082     * Returns the canonical form of a page name. The canonical form uses character case matching the underlying class
083     * name.
084     * 
085     * @throws org.apache.tapestry5.ioc.util.UnknownValueException
086     *             if the page name does not match a logical page name
087     */
088    String canonicalizePageName(String pageName);
089
090    /**
091     * Converts a component type (a logical component name such as might be used inside a template or annotation) into a
092     * fully qualified class name. Case is ignored in resolving the name.
093     * 
094     * @param componentType
095     *            a logical component type
096     * @return fully qualified class name
097     * @throws org.apache.tapestry5.ioc.util.UnknownValueException
098     *             if the component type can not be resolved
099     */
100    String resolveComponentTypeToClassName(String componentType);
101
102    /**
103     * Converts a logical mixin type (as with component types) into a fully qualified class name. Case is ignored when
104     * resolving the name.
105     * 
106     * @param mixinType
107     *            a logical mixin type
108     * @return fully qualified class name
109     * @throws org.apache.tapestry5.ioc.util.UnknownValueException
110     *             if the mixin type can not be resolved
111     */
112    String resolveMixinTypeToClassName(String mixinType);
113
114    /**
115     * A mapping from virtual folder name to a package name (used for converting classpath {@link Asset}s
116     * to client URLs). This is derived from the contributed {@link LibraryMapping}s.
117     * <p>
118     * It is allowed to contribute multiple root packages as a single folder name. In this case, the best common package
119     * name is used. For example, if both <code>com.example.main</code> and <code>com.example.extras</code> is mapped to
120     * folder "example", then the package mapping for "example" will be <code>com.example</code>.
121     * 
122     * @since 5.2.0
123     * @see ClasspathAssetAliasManager
124     */
125    Map<String, String> getFolderToPackageMapping();
126
127    /**
128     * Used to identify which packages are controlled packages (from which components are loaded). Future expansion
129     * may allow for additional packages which are live reloaded but not components (or perhaps are transformed, but not
130     * as components).
131     * 
132     * @return a mapping from package name to {@link ControlledPackageType}.
133     * @since 5.3
134     */
135    Map<String, ControlledPackageType> getControlledPackageMapping();
136
137    /**
138     * Returns true if the class name is specifically a page class, and not a component, mixin or base class.
139     * 
140     * @param pageClassName
141     * @return true if a page class
142     * @since 5.3
143     */
144    boolean isPage(final String pageClassName);
145}