001// Copyright 2004, 2005 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.tapestry; 016 017import java.util.List; 018 019import org.apache.hivemind.Locatable; 020import org.apache.hivemind.Resource; 021import org.apache.tapestry.engine.IPropertySource; 022import org.apache.tapestry.spec.IComponentSpecification; 023import org.apache.tapestry.spec.ILibrarySpecification; 024 025/** 026 * Organizes different libraries of Tapestry pages, components and services into "frameworks", used 027 * to disambiguate names. 028 * <p> 029 * Tapestry release 3.0 includes dynamic discovery of pages and components; an application or 030 * library may contain a page or component that won't be "known" until the name is resolved (because 031 * it involves searching for a particular named file). 032 * <p> 033 * A namespace implements {@link org.apache.tapestry.engine.IPropertySource}, exposing the 034 * properties provided in the namespace's specification. 035 * 036 * @see org.apache.tapestry.resolver.PageSpecificationResolver 037 * @see org.apache.tapestry.resolver.ComponentSpecificationResolver 038 * @author Howard Lewis Ship 039 * @since 2.2 040 */ 041 042public interface INamespace extends Locatable, IPropertySource 043{ 044 /** 045 * Reserved name of a the implicit Framework library. 046 */ 047 048 public static final String FRAMEWORK_NAMESPACE = "framework"; 049 050 /** 051 * Reserved name for the implicit (root) application namespace. Use of this prefix allows page 052 * or component defined in the application to be referenced from a library. Is this a good 053 * thing? In rare cases, yes. Is it subject to severe abuse? Yes. 054 * 055 * @since 4.0 056 */ 057 058 public static final String APPLICATION_NAMESPACE = "application"; 059 060 /** 061 * Character used to seperate the namespace prefix from the page name or component type. 062 * 063 * @since 2.3 064 */ 065 066 public static final char SEPARATOR = ':'; 067 068 /** 069 * Returns an identifier for the namespace. Identifiers are simple names (they start with a 070 * letter, and may contain letters, numbers, underscores and dashes). An identifier must be 071 * unique among a namespaces siblings. 072 * <p> 073 * The application namespace has a null id; the framework namespace has an id of "framework". 074 */ 075 076 public String getId(); 077 078 /** 079 * Returns the extended id for this namespace, which is a dot-seperated sequence of ids. 080 */ 081 082 public String getExtendedId(); 083 084 /** 085 * Returns a version of the extended id appropriate for error messages. This is the based on 086 * {@link #getExtendedId()}, unless this is the application or framework namespace, in which 087 * case special strings are returned. 088 * 089 * @since 3.0 090 */ 091 092 public String getNamespaceId(); 093 094 /** 095 * Returns the parent namespace; the namespace which contains this namespace. 096 * <p> 097 * The application and framework namespaces return null as the parent. 098 */ 099 100 public INamespace getParentNamespace(); 101 102 /** 103 * Returns a namespace contained by this namespace. 104 * 105 * @param id 106 * either a simple name (of a directly contained namespace), or a dot-separated name 107 * sequence 108 * @return the child namespace 109 * @throws ApplicationRuntimeException 110 * if no such namespace exist. 111 */ 112 113 public INamespace getChildNamespace(String id); 114 115 /** 116 * Returns a sorted, immutable list of the ids of the immediate children of this namespace. May 117 * return the empty list, but won't return null. 118 */ 119 120 public List getChildIds(); 121 122 /** 123 * Returns the page specification of the named page (defined within the namespace). 124 * 125 * @param name 126 * the name of the page 127 * @return the specification 128 * @throws ApplicationRuntimeException 129 * if the page specification doesn't exist or can't be loaded 130 */ 131 132 public IComponentSpecification getPageSpecification(String name); 133 134 /** 135 * Returns true if this namespace contains the specified page name. 136 */ 137 138 public boolean containsPage(String name); 139 140 /** 141 * Returns a sorted list of page names. May return an empty list, but won't return null. The 142 * return list is immutable. 143 */ 144 145 public List getPageNames(); 146 147 /** 148 * Returns the path for the named component (within the namespace). 149 * 150 * @param type 151 * the component type 152 * @return the specification for the component 153 * @throws ApplicationRuntimeException 154 * if the specification doesn't exist or can't be loaded 155 */ 156 157 public IComponentSpecification getComponentSpecification(String type); 158 159 /** 160 * Returns true if the namespace contains the indicated component type. 161 * 162 * @param type 163 * a simple component type (no namespace prefix is allowed) 164 */ 165 166 public boolean containsComponentType(String type); 167 168 /** 169 * Returns the {@link org.apache.tapestry.spec.LibrarySpecification}from which this namespace 170 * was created. 171 */ 172 173 public ILibrarySpecification getSpecification(); 174 175 /** 176 * Constructs a qualified name for the given simple page name by applying the correct prefix (if 177 * any). 178 * 179 * @since 2.3 180 */ 181 182 public String constructQualifiedName(String pageName); 183 184 /** 185 * Returns the location of the resource from which the specification for this namespace was 186 * read. 187 */ 188 189 public Resource getSpecificationLocation(); 190 191 /** 192 * Returns true if the namespace is the special application namespace (which has special search 193 * rules for handling undeclared pages and components). 194 * 195 * @since 3.0 196 */ 197 198 public boolean isApplicationNamespace(); 199 200 /** 201 * Used to specify additional pages beyond those that came from the namespace's specification. 202 * This is used when pages in the application namespace are dynamically discovered. 203 * 204 * @since 3.0 205 */ 206 207 public void installPageSpecification(String pageName, IComponentSpecification specification); 208 209 /** 210 * Used to specify additional components beyond those that came from the namespace's 211 * specification. This is used when components in the application namespace are dynamically 212 * discovered. 213 * 214 * @since 3.0 215 */ 216 217 public void installComponentSpecification(String type, IComponentSpecification specification); 218 219}