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    }