Coverage Report - org.apache.tapestry.INamespace
 
Classes in this File Line Coverage Branch Coverage Complexity
INamespace
N/A
N/A
1
 
 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  
     String FRAMEWORK_NAMESPACE = "framework";
 50  
 
 51  
     /**
 52  
      * Reserved name for the implicit (root) application namespace. Use of this prefix allows page
 53  
      * or component defined in the application to be referenced from a library. Is this a good
 54  
      * thing? In rare cases, yes. Is it subject to severe abuse? Yes.
 55  
      * 
 56  
      * @since 4.0
 57  
      */
 58  
 
 59  
     String APPLICATION_NAMESPACE = "application";
 60  
 
 61  
     /**
 62  
      * Character used to seperate the namespace prefix from the page name or component type.
 63  
      * 
 64  
      * @since 2.3
 65  
      */
 66  
 
 67  
     char SEPARATOR = ':';
 68  
 
 69  
     /**
 70  
      * Returns an identifier for the namespace. Identifiers are simple names (they start with a
 71  
      * letter, and may contain letters, numbers, underscores and dashes). An identifier must be
 72  
      * unique among a namespaces siblings.
 73  
      * <p>
 74  
      * The application namespace has a null id; the framework namespace has an id of "framework".
 75  
      */
 76  
 
 77  
     String getId();
 78  
 
 79  
     /**
 80  
      * Returns the extended id for this namespace, which is a dot-seperated sequence of ids.
 81  
      */
 82  
 
 83  
     String getExtendedId();
 84  
 
 85  
     /**
 86  
      * Returns a version of the extended id appropriate for error messages. This is the based on
 87  
      * {@link #getExtendedId()}, unless this is the application or framework namespace, in which
 88  
      * case special strings are returned.
 89  
      * 
 90  
      * @since 3.0
 91  
      */
 92  
 
 93  
     String getNamespaceId();
 94  
 
 95  
     /**
 96  
      * Returns the parent namespace; the namespace which contains this namespace.
 97  
      * <p>
 98  
      * The application and framework namespaces return null as the parent.
 99  
      */
 100  
 
 101  
     INamespace getParentNamespace();
 102  
 
 103  
     /**
 104  
      * Returns a namespace contained by this namespace.
 105  
      * 
 106  
      * @param id
 107  
      *            either a simple name (of a directly contained namespace), or a dot-separated name
 108  
      *            sequence
 109  
      * @return the child namespace
 110  
      * @throws ApplicationRuntimeException
 111  
      *             if no such namespace exist.
 112  
      */
 113  
 
 114  
     INamespace getChildNamespace(String id);
 115  
 
 116  
     /**
 117  
      * Returns a sorted, immutable list of the ids of the immediate children of this namespace. May
 118  
      * return the empty list, but won't return null.
 119  
      */
 120  
 
 121  
     List getChildIds();
 122  
 
 123  
     /**
 124  
      * Returns the page specification of the named page (defined within the namespace).
 125  
      * 
 126  
      * @param name
 127  
      *            the name of the page
 128  
      * @return the specification
 129  
      * @throws ApplicationRuntimeException
 130  
      *             if the page specification doesn't exist or can't be loaded
 131  
      */
 132  
 
 133  
     IComponentSpecification getPageSpecification(String name);
 134  
 
 135  
     /**
 136  
      * Returns true if this namespace contains the specified page name.
 137  
      */
 138  
 
 139  
     boolean containsPage(String name);
 140  
 
 141  
     /**
 142  
      * Returns a sorted list of page names. May return an empty list, but won't return null. The
 143  
      * return list is immutable.
 144  
      */
 145  
 
 146  
     List getPageNames();
 147  
 
 148  
     /**
 149  
      * Returns the path for the named component (within the namespace).
 150  
      * 
 151  
      * @param type
 152  
      *            the component type
 153  
      * @return the specification for the component
 154  
      * @throws ApplicationRuntimeException
 155  
      *             if the specification doesn't exist or can't be loaded
 156  
      */
 157  
 
 158  
     IComponentSpecification getComponentSpecification(String type);
 159  
 
 160  
     /**
 161  
      * Returns true if the namespace contains the indicated component type.
 162  
      * 
 163  
      * @param type
 164  
      *            a simple component type (no namespace prefix is allowed)
 165  
      */
 166  
 
 167  
     boolean containsComponentType(String type);
 168  
 
 169  
     /**
 170  
      * Returns the {@link org.apache.tapestry.spec.LibrarySpecification}from which this namespace
 171  
      * was created.
 172  
      */
 173  
 
 174  
     ILibrarySpecification getSpecification();
 175  
 
 176  
     /**
 177  
      * Constructs a qualified name for the given simple page name by applying the correct prefix (if
 178  
      * any).
 179  
      * 
 180  
      * @since 2.3
 181  
      */
 182  
 
 183  
     String constructQualifiedName(String pageName);
 184  
 
 185  
     /**
 186  
      * Returns the location of the resource from which the specification for this namespace was
 187  
      * read.
 188  
      */
 189  
 
 190  
     Resource getSpecificationLocation();
 191  
 
 192  
     /**
 193  
      * Returns true if the namespace is the special application namespace (which has special search
 194  
      * rules for handling undeclared pages and components).
 195  
      * 
 196  
      * @since 3.0
 197  
      */
 198  
 
 199  
     boolean isApplicationNamespace();
 200  
 
 201  
     /**
 202  
      * Used to specify additional pages beyond those that came from the namespace's specification.
 203  
      * This is used when pages in the application namespace are dynamically discovered.
 204  
      * 
 205  
      * @since 3.0
 206  
      */
 207  
 
 208  
     void installPageSpecification(String pageName, IComponentSpecification specification);
 209  
 
 210  
     /**
 211  
      * Used to specify additional components beyond those that came from the namespace's
 212  
      * specification. This is used when components in the application namespace are dynamically
 213  
      * discovered.
 214  
      * 
 215  
      * @since 3.0
 216  
      */
 217  
 
 218  
     void installComponentSpecification(String type, IComponentSpecification specification);
 219  
 
 220  
 }