001: // Copyright 2006, 2007 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.tapestry.services;
016:
017: import org.apache.tapestry.internal.services.ClassNameLocator;
018:
019: /**
020: * Resolves page names and component types to fully qualified class names. Pages and components may
021: * be provided by the application or inside a <em>mapped package</em>. Page names often appear
022: * inside URLs, and component types often appear in component template (when specifying the type of
023: * an embedded component).
024: * <p>
025: * The service is configured using a collection of {@link LibraryMapping}s. Each mapping maps a
026: * prefix, such as "core" to a root package name, such as "org.apache.tapestry.corelib". The root
027: * package is expected to have sub-packages: "pages", "components", "mixins" and "base" ("base" is
028: * for base classes).
029: * <p>
030: * The resolver performs a search of the classpath (via {@link ClassNameLocator}, to build up a set
031: * of case-insensitive maps from logical page name, component type, or mixin type to fully qualified
032: * class name.
033: * <p>
034: * Certain ambiguities occur if mapped packages overlap, either in terms of the the prefixes or the
035: * package names. Keep things clearly seperate to avoid lookup problems.
036: */
037: public interface ComponentClassResolver {
038: /**
039: * Converts a logical page name (such as might be encoded into a URL) into a fully qualified
040: * class name. The case of the page name is irrelevant.
041: *
042: * @param logicalPageName
043: * logical page name
044: * @return fully qualified class name for the page
045: * @throws IllegalArgumentException
046: * if the name does not match a known page class
047: */
048: String resolvePageNameToClassName(String logicalPageName);
049:
050: /**
051: * For a particular path, determines if the path is a logical page name. The check is case
052: * insensitive.
053: *
054: * @param pageName
055: * potential logical page name
056: * @return true if the page name is valid
057: */
058: boolean isPageName(String pageName);
059:
060: /**
061: * Converts a fully qualified page class name into a logical class name (often, for inclusion as
062: * part of the URI). This value may later be passed to
063: * {@link #resolvePageNameToClassName(String)}.
064: *
065: * @param pageClassName
066: * fully qualified name of a page class
067: * @return equivalent logical page name
068: * @throws IllegalArgumentException
069: * if the name can not be resolved
070: */
071: String resolvePageClassNameToPageName(String pageClassName);
072:
073: /**
074: * Returns the canonical form of a logical page name. The canonical form uses character case
075: * matching the underlying class name.
076: *
077: * @throws IllegalArgumentException
078: * if the page name does not match a logical page name
079: */
080: String canonicalizePageName(String pageName);
081:
082: /**
083: * Converts a component type (a logical component name such as might be used inside a template
084: * or annotation) into a fully qualified class name. Case is ignored in resolving the name.
085: *
086: * @param componentType
087: * a logical component type
088: * @return fully qualified class name
089: * @throws IllegalArgumentException
090: * if the component type can not be resolved
091: */
092: String resolveComponentTypeToClassName(String componentType);
093:
094: /**
095: * Converts a logical mixin type (as with component types) into a fully qualified class name.
096: * Case is ignored when resolving the name.
097: *
098: * @param mixinType
099: * a logical mixin type
100: * @return fully qualified class name
101: * @throws IllegalArgumentException
102: * if the mixin type can not be resolved
103: */
104: String resolveMixinTypeToClassName(String mixinType);
105: }
|