/*
 Copyright (c) 2007 Eric J. Feminella <eric@ericfeminella.com>
 All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy 
 of this software and associated documentation files (the "Software"), to deal 
 in the Software without restriction, including without limitation the rights 
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is furnished 
 to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all 
 copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
 INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
 PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 @internal
 */

package com.ericfeminella.ns
{
    /**
     *  
     * <code>INamespaceManager</code> defines the contract for 
     * <code>Namespace</code> management APIs which are utilized 
     * by classes and components within an application to retrieve 
     * the unique <code>Namespace</code> under which the current 
     * context of an application is executing
     * 
     * @see Namespace
     * 
     */    
    public interface INamespaceManager
    {            
        /**
         * 
         * Retrieves the qualified namespace object which is based on
         * the current context in which the application is executing
         * 
         * <p>
         * The namespace referenced by <code>getNamespace</code> is to 
         * be utilized to determine the context from which methods are 
         * to be invoked on an object or <code>Class</code>
         * </p>
         * 
         * @return the current contextual <code>Namespace</code> 
         * 
         */        
        function getNamespace() : Namespace;

        /**
         * 
         * Sets the qualified namespace object based on the current 
         * context of the application
         * 
         * <p>
         * The namespace referenced by <code>getNamespace</code> is to 
         * be utilized to determine the context from which methods are 
         * called. This namespace is set by <code>setNamespace</code>
         * </p>
         *  
         * @param the contextual Namespace of the application
         * 
         */        
        function setNamespace(ns:Namespace) : void;
            
        /**
         * 
         * Retrieves the qualified namespace URI of the current
         * namespace
         * 
         * @return URI of the current <code>Namespace</code>
         * 
         */        
        function get namespaceURI() : String;
        
        /**
         * 
         * Retrieves the qualified namespace prefix from the current
         * namespace
         * 
         * @return namespace prefix for the current namespace
         * 
         */        
        function get namespacePrefix() : String;
        
        /**
         *
         * Determines if the current contextual <code>Namespace</code> 
         * is that of the specified <code>Namespace</code>
         * 
         * @param   the namespace to determine a contextual match
         * @return  true of the current namespaces are equal, otherwise false
         * 
         */        
        function isCurrentContext(ns:Namespace) : Boolean;
        
        /**
         *
         * Determines if the current contextual <code>Namespace</code> 
         * URI is equal to that of the specified <code>Namespace</code>
         * 
         * @param   the namespace URI in which to determine a contextual match
         * @return  true of the current namespaces are equal, otherwise false
         * 
         */        
        function isCurrentURI(uri:String) : Boolean;
    }
}