INamespace


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.tapestry;
16  
17  import java.util.List  ;
18  
19  import org.apache.hivemind.ApplicationRuntimeException;
20  import org.apache.hivemind.Locatable;
21  import org.apache.hivemind.Resource;
22  import org.apache.tapestry.engine.IPropertySource;
23  import org.apache.tapestry.spec.IComponentSpecification;
24  import org.apache.tapestry.spec.ILibrarySpecification;
25  
26  /**
27   * Organizes different libraries of Tapestry pages, components and services into "frameworks", used
28   * to disambiguate names.
29   * <p>
30   * Tapestry release 3.0 includes dynamic discovery of pages and components; an application or
31   * library may contain a page or component that won't be "known" until the name is resolved (because
32   * it involves searching for a particular named file).
33   * <p>
34   * A namespace implements {@link org.apache.tapestry.engine.IPropertySource}, exposing the
35   * properties provided in the namespace's specification.
36   * 
37   * @see org.apache.tapestry.resolver.PageSpecificationResolver
38   * @see org.apache.tapestry.resolver.ComponentSpecificationResolver
39   * @author Howard Lewis Ship
40   * @since 2.2
41   */
42  
43  public interface INamespace extends Locatable, IPropertySource
44  {
45      /**
46       * Reserved name of a the implicit Framework library.
47       */
48  
49      public static final String   FRAMEWORK_NAMESPACE = "framework";
50  
51      /**
52       * Character used to seperate the namespace prefix from the page name or component type.
53       * 
54       * @since 2.3
55       */
56  
57      public static final char SEPARATOR = ':';
58  
59      /**
60       * Returns an identifier for the namespace. Identifiers are simple names (they start with a
61       * letter, and may contain letters, numbers, underscores and dashes). An identifier must be
62       * unique among a namespaces siblings.
63       * <p>
64       * The application namespace has a null id; the framework namespace has an id of "framework".
65       */
66  
67      public String   getId();
68  
69      /**
70       * Returns the extended id for this namespace, which is a dot-seperated sequence of ids.
71       */
72  
73      public String   getExtendedId();
74  
75      /**
76       * Returns a version of the extended id appropriate for error messages. This is the based on
77       * {@link #getExtendedId()}, unless this is the application or framework namespace, in which
78       * case special strings are returned.
79       * 
80       * @since 3.0
81       */
82  
83      public String   getNamespaceId();
84  
85      /**
86       * Returns the parent namespace; the namespace which contains this namespace.
87       * <p>
88       * The application and framework namespaces return null as the parent.
89       */
90  
91      public INamespace getParentNamespace();
92  
93      /**
94       * Returns a namespace contained by this namespace.
95       * 
96       * @param id
97       *            either a simple name (of a directly contained namespace), or a dot-seperarated
98       *            name sequence.
99       * @return the child namespace
100      * @throws ApplicationRuntimeException
101      *             if no such namespace exist.
102      */
103 
104     public INamespace getChildNamespace(String   id);
105 
106     /**
107      * Returns a sorted, immutable list of the ids of the immediate children of this namespace. May
108      * return the empty list, but won't return null.
109      */
110 
111     public List   getChildIds();
112 
113     /**
114      * Returns the page specification of the named page (defined within the namespace).
115      * 
116      * @param name
117      *            the name of the page
118      * @return the specification
119      * @throws ApplicationRuntimeException
120      *             if the page specification doesn't exist or can't be loaded
121      */
122 
123     public IComponentSpecification getPageSpecification(String   name);
124 
125     /**
126      * Returns true if this namespace contains the specified page name.
127      */
128 
129     public boolean containsPage(String   name);
130 
131     /**
132      * Returns a sorted list of page names. May return an empty list, but won't return null. The
133      * return list is immutable.
134      */
135 
136     public List   getPageNames();
137 
138     /**
139      * Returns the path for the named component (within the namespace).
140      * 
141      * @param type
142      *            the component alias
143      * @return the specification path of the component
144      * @throws ApplicationRuntimeException
145      *             if the specification doesn't exist or can't be loaded
146      */
147 
148     public IComponentSpecification getComponentSpecification(String   type);
149 
150     /**
151      * Returns true if the namespace contains the indicated component type.
152      * 
153      * @param type
154      *            a simple component type (no namespace prefix is allowed)
155      */
156 
157     public boolean containsComponentType(String   type);
158 
159     /**
160      * Returns the {@link org.apache.tapestry.spec.LibrarySpecification}from which this namespace
161      * was created.
162      */
163 
164     public ILibrarySpecification getSpecification();
165 
166     /**
167      * Constructs a qualified name for the given simple page name by applying the correct prefix (if
168      * any).
169      * 
170      * @since 2.3
171      */
172 
173     public String   constructQualifiedName(String   pageName);
174 
175     /**
176      * Returns the location of the resource from which the specification for this namespace was
177      * read.
178      */
179 
180     public Resource getSpecificationLocation();
181 
182     /**
183      * Returns true if the namespace is the special application namespace (which has special search
184      * rules for handling undeclared pages and components).
185      * 
186      * @since 3.0
187      */
188 
189     public boolean isApplicationNamespace();
190 
191     /**
192      * Used to specify additional pages beyond those that came from the namespace's specification.
193      * This is used when pages in the application namespace are dynamically discovered.
194      * 
195      * @since 3.0
196      */
197 
198     public void installPageSpecification(String   pageName, IComponentSpecification specification);
199 
200     /**
201      * Used to specify additional components beyond those that came from the namespace's
202      * specification. This is used when components in the application namespace are dynamically
203      * discovered.
204      * 
205      * @since 3.0
206      */
207 
208     public void installComponentSpecification(String   type, IComponentSpecification specification);
209 
210 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags