| // Copyright 2004 The Apache Software Foundation |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package org.apache.tapestry; |
| |
| import java.util.List; |
| |
| import org.apache.tapestry.spec.IComponentSpecification; |
| import org.apache.tapestry.spec.ILibrarySpecification; |
| |
| /** |
| * Organizes different libraries of Tapestry pages, components |
| * and services into "frameworks", used to disambiguate names. |
| * |
| * <p> |
| * Tapestry release 3.0 includes dynamic discovery of pages and components; an application |
| * or library may contain a page or component that won't be "known" until the name |
| * is resolved (because it involves searching for a particular named file). |
| * |
| * @see org.apache.tapestry.resolver.PageSpecificationResolver |
| * @see org.apache.tapestry.resolver.ComponentSpecificationResolver |
| * |
| * @author Howard Lewis Ship |
| * @version $Id$ |
| * @since 2.2 |
| * |
| **/ |
| |
| public interface INamespace extends ILocatable |
| { |
| /** |
| * Reserved name of a the implicit Framework library. |
| * |
| **/ |
| |
| public static final String FRAMEWORK_NAMESPACE = "framework"; |
| |
| /** |
| * Character used to seperate the namespace prefix from the page name |
| * or component type. |
| * |
| * @since 2.3 |
| * |
| **/ |
| |
| public static final char SEPARATOR = ':'; |
| |
| /** |
| * Returns an identifier for the namespace. Identifiers |
| * are simple names (they start with a letter, |
| * and may contain letters, numbers, underscores and dashes). |
| * An identifier must be unique among a namespaces siblings. |
| * |
| * <p>The application namespace has a null id; the framework |
| * namespace has an id of "framework". |
| * |
| **/ |
| |
| public String getId(); |
| |
| /** |
| * Returns the extended id for this namespace, which is |
| * a dot-seperated sequence of ids. |
| * |
| **/ |
| |
| public String getExtendedId(); |
| |
| /** |
| * Returns a version of the extended id appropriate for error |
| * messages. This is the based on |
| * {@link #getExtendedId()}, unless this is the |
| * application or framework namespace, in which case |
| * special strings are returned. |
| * |
| * @since 3.0 |
| * |
| **/ |
| |
| public String getNamespaceId(); |
| |
| /** |
| * Returns the parent namespace; the namespace which |
| * contains this namespace. |
| * |
| * <p> |
| * The application and framework namespaces return null |
| * as the parent. |
| * |
| **/ |
| |
| public INamespace getParentNamespace(); |
| |
| /** |
| * Returns a namespace contained by this namespace. |
| * |
| * @param id either a simple name (of a directly contained namespace), |
| * or a dot-seperarated name sequence. |
| * @return the child namespace |
| * @throws ApplicationRuntimeException if no such namespace exist. |
| * |
| **/ |
| |
| public INamespace getChildNamespace(String id); |
| |
| /** |
| * Returns a sorted, immutable list of the ids of the immediate |
| * children of this namespace. May return the empty list, |
| * but won't return null. |
| * |
| **/ |
| |
| public List getChildIds(); |
| |
| /** |
| * Returns the page specification of the named |
| * page (defined within the namespace). |
| * |
| * @param name the name of the page |
| * @return the specification |
| * @throws ApplicationRuntimeException if the page specification |
| * doesn't exist or can't be loaded |
| * |
| **/ |
| |
| public IComponentSpecification getPageSpecification(String name); |
| |
| /** |
| * Returns true if this namespace contains the specified |
| * page name. |
| * |
| **/ |
| |
| public boolean containsPage(String name); |
| |
| /** |
| * Returns a sorted list of page names. May return an empty |
| * list, but won't return null. The return list is immutable. |
| * |
| **/ |
| |
| public List getPageNames(); |
| |
| /** |
| * Returns the path for the named component (within the namespace). |
| * |
| * @param type the component alias |
| * @return the specification path of the component |
| * @throws ApplicationRuntimeException if the specification |
| * doesn't exist or can't be loaded |
| * |
| **/ |
| |
| public IComponentSpecification getComponentSpecification(String type); |
| |
| /** |
| * Returns true if the namespace contains the indicated component type. |
| * |
| * @param type a simple component type (no namespace prefix is allowed) |
| * |
| **/ |
| |
| public boolean containsComponentType(String type); |
| |
| /** |
| * Returns a sorted list of component types. May return |
| * an empty list, but won't return null. The return list |
| * is immutable. Represents just the known component types |
| * (additional types may be discoverred dynamically). |
| * |
| * <p>Is this method even needed? |
| * |
| * @since 3.0 |
| * |
| **/ |
| |
| public List getComponentTypes(); |
| |
| /** |
| * Returns the class name of a service provided by the |
| * namespace. |
| * |
| * @param name the name of the service. |
| * @return the complete class name of the service, or null |
| * if the namespace does not contain the named service. |
| * |
| **/ |
| |
| public String getServiceClassName(String name); |
| |
| /** |
| * Returns the names of all services provided by the |
| * namespace, as a sorted, immutable list. May return |
| * the empty list, but won't return null. |
| * |
| **/ |
| |
| public List getServiceNames(); |
| |
| /** |
| * Returns the {@link org.apache.tapestry.spec.LibrarySpecification} from which |
| * this namespace was created. |
| * |
| **/ |
| |
| public ILibrarySpecification getSpecification(); |
| |
| /** |
| * Constructs a qualified name for the given simple page name by |
| * applying the correct prefix (if any). |
| * |
| * @since 2.3 |
| * |
| **/ |
| |
| public String constructQualifiedName(String pageName); |
| |
| /** |
| * Returns the location of the resource from which the |
| * specification for this namespace was read. |
| * |
| **/ |
| |
| public IResourceLocation getSpecificationLocation(); |
| |
| /** |
| * Returns true if the namespace is the special |
| * application namespace (which has special search rules |
| * for handling undeclared pages and components). |
| * |
| * @since 3.0 |
| * |
| **/ |
| |
| public boolean isApplicationNamespace(); |
| |
| /** |
| * Used to specify additional pages beyond those that came from |
| * the namespace's specification. This is used when pages |
| * in the application namespace are dynamically discovered. |
| * |
| * @since 3.0 |
| * |
| **/ |
| |
| public void installPageSpecification(String pageName, IComponentSpecification specification); |
| |
| /** |
| * Used to specify additional components beyond those that came from |
| * the namespace's specification. This is used when components |
| * in the application namespace are dynamically discovered. |
| * |
| * @since 3.0 |
| * |
| **/ |
| |
| public void installComponentSpecification(String type, IComponentSpecification specification); |
| |
| } |