Clover coverage report - Code Coverage for tapestry release 4.0.2
Coverage timestamp: Thu Apr 13 2006 10:52:06 EDT
file stats: LOC: 219   Methods: 0
NCLOC: 29   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
INamespace.java - - - -
coverage
 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.Locatable;
 20    import org.apache.hivemind.Resource;
 21    import org.apache.tapestry.engine.IPropertySource;
 22    import org.apache.tapestry.spec.IComponentSpecification;
 23    import org.apache.tapestry.spec.ILibrarySpecification;
 24   
 25    /**
 26    * Organizes different libraries of Tapestry pages, components and services into "frameworks", used
 27    * to disambiguate names.
 28    * <p>
 29    * Tapestry release 3.0 includes dynamic discovery of pages and components; an application or
 30    * library may contain a page or component that won't be "known" until the name is resolved (because
 31    * it involves searching for a particular named file).
 32    * <p>
 33    * A namespace implements {@link org.apache.tapestry.engine.IPropertySource}, exposing the
 34    * properties provided in the namespace's specification.
 35    *
 36    * @see org.apache.tapestry.resolver.PageSpecificationResolver
 37    * @see org.apache.tapestry.resolver.ComponentSpecificationResolver
 38    * @author Howard Lewis Ship
 39    * @since 2.2
 40    */
 41   
 42    public interface INamespace extends Locatable, IPropertySource
 43    {
 44    /**
 45    * Reserved name of a the implicit Framework library.
 46    */
 47   
 48    public static final String FRAMEWORK_NAMESPACE = "framework";
 49   
 50    /**
 51    * Reserved name for the implicit (root) application namespace. Use of this prefix allows page
 52    * or component defined in the application to be referenced from a library. Is this a good
 53    * thing? In rare cases, yes. Is it subject to severe abuse? Yes.
 54    *
 55    * @since 4.0
 56    */
 57   
 58    public static final String APPLICATION_NAMESPACE = "application";
 59   
 60    /**
 61    * Character used to seperate the namespace prefix from the page name or component type.
 62    *
 63    * @since 2.3
 64    */
 65   
 66    public static final char SEPARATOR = ':';
 67   
 68    /**
 69    * Returns an identifier for the namespace. Identifiers are simple names (they start with a
 70    * letter, and may contain letters, numbers, underscores and dashes). An identifier must be
 71    * unique among a namespaces siblings.
 72    * <p>
 73    * The application namespace has a null id; the framework namespace has an id of "framework".
 74    */
 75   
 76    public String getId();
 77   
 78    /**
 79    * Returns the extended id for this namespace, which is a dot-seperated sequence of ids.
 80    */
 81   
 82    public String getExtendedId();
 83   
 84    /**
 85    * Returns a version of the extended id appropriate for error messages. This is the based on
 86    * {@link #getExtendedId()}, unless this is the application or framework namespace, in which
 87    * case special strings are returned.
 88    *
 89    * @since 3.0
 90    */
 91   
 92    public String getNamespaceId();
 93   
 94    /**
 95    * Returns the parent namespace; the namespace which contains this namespace.
 96    * <p>
 97    * The application and framework namespaces return null as the parent.
 98    */
 99   
 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    }