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.Locatable;
020 import org.apache.hivemind.Resource;
021 import org.apache.tapestry.engine.IPropertySource;
022 import org.apache.tapestry.spec.IComponentSpecification;
023 import 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
042 public 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 }