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}