001// Copyright 2006, 2007, 2008, 2009, 2010, 2011, 2012 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.Asset; 018import org.apache.tapestry5.ioc.annotations.UsesConfiguration; 019import org.apache.tapestry5.ioc.services.ClassNameLocator; 020import org.apache.tapestry5.services.transform.ControlledPackageType; 021 022import java.util.List; 023import java.util.Map; 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 templates (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. These are the "canonical" page names. 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 * @see ClasspathAssetAliasManager 123 * @since 5.2.0 124 */ 125 Map<String, String> getFolderToPackageMapping(); 126 127 /** 128 * Returns the names of all libraries (as {@linkplain org.apache.tapestry5.services.LibraryMapping#getPathPrefix() configured}). 129 * This does not include the application itself (which is a library with the virtual path of empty string). 130 * 131 * @return sorted names of libraries 132 * @since 5.4 133 */ 134 List<String> getLibraryNames(); 135 136 /** 137 * Used to identify which packages are controlled packages (from which components are loaded). Future expansion 138 * may allow for additional packages which are live reloaded but not components (or perhaps are transformed, but not 139 * as components). 140 * 141 * @return a mapping from package name to {@link ControlledPackageType}. 142 * @since 5.3 143 */ 144 Map<String, ControlledPackageType> getControlledPackageMapping(); 145 146 /** 147 * Returns true if the class name is specifically a page class, and not a component, mixin or base class. 148 * 149 * @param pageClassName 150 * @return true if a page class 151 * @since 5.3 152 */ 153 boolean isPage(final String pageClassName); 154 155 /** 156 * Given a class name of a component class, returns the library name (as defined by a 157 * {@linkplain org.apache.tapestry5.services.LibraryMapping#getPathPrefix() contributed library name}). 158 * 159 * @param className 160 * @return library name 161 * @throws IllegalArgumentException 162 * if the class can't be matched to a contributed root package 163 */ 164 String getLibraryNameForClass(String className); 165}