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