/**
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You 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.aries.blueprint;

import java.net.URL;
import java.util.Set;

import org.w3c.dom.Element;
import org.w3c.dom.Node;

import org.osgi.service.blueprint.reflect.ComponentMetadata;
import org.osgi.service.blueprint.reflect.Metadata;

/**
 * A processor for custom blueprint extensions
 * 
 * Namespace handlers must be registered in the OSGi service registry with the 
 * <code>osgi.service.blueprint.namespace</code> service property denoting the namespace URIs this
 * handler can process. The service property value can be either a single <code>String</code> or <code>URI</code>, 
 * or a <code>Collection</code> respectively array of <code>String</code> or <code>URI</code>.
 * 
 * During parsing when the blueprint extender encounters an element from a non-blueprint namespace it will search
 * for a namespace handler for the namespace that is compatible with blueprint bundle being processed. Then
 * for a stand-alone component the parser will invoke the <code>parse</code> method 
 * to create the <code>Metadata</code> for the xml element while for an element that is part
 * of an existing component the parser will invoke the <code>decorated</code> method to augment
 * the enclosing <code>ComponentMetadata</code> instance.  Various utilities to interact with 
 * the blueprint parser are available to a namespace handler via the <code>ParserContext</code> argument 
 * passed to <code>parse</code> and <code>decorate</code>.
 * 
 * Recommended behaviour:
 * <ul>
 * <li>New metadata objects should be created via calling <code>ParserContext.createMetadata(..)</code> and
 * casting the returned object to the appropriate <code>MutableComponentMetadata</code> interface. 
 * This method ensures that the metadata object implements the interfaces necessary for other namespace handlers
 * to be able to use the metadata object.<br/>
 * Also, to prevent id clashes, component ids should be generated by calling <code>ParserContext.generateId()</code>.
 * </li>
 * <li>A namespace handler should not return new metadata instances from the <code>decorate</code> method if 
 * the same result could also be achieved by operating on a <code>MutableComponentMetadata</code> instance.
 * </li>
 * <li>A namespace handler should not assume the existence of predefined entries in the component definition
 * registry such as <code>blueprintBundle</code> or <code>blueprintBundleContext</code>. In the case of a dry
 * parse (i.e. a parse of the blueprint xml files without a backing OSGi bundle), these values will not be 
 * available
 * </li>
 * </ul>
 */
public interface NamespaceHandler  {
    /**
     * Retrieve a URL from where the schema for a given namespace can be retrieved
     * @param namespace The schema's namespace
     * @return A URL that points to the location of the schema or null if the namespace validation
     * is not needed
     */
    URL getSchemaLocation(String namespace);

    /**
     * Specify a set of classes that must be consistent between a blueprint bundle and this namespace handler
     * 
     * The blueprint extender will not invoke a namespace handler if any of the managed classes are inconsistent
     * with the class space of the blueprint bundle (i.e. if the blueprint bundle loads any of the managed classes
     * from a different classloader).
     * 
     * @return a <code>Set</code> of classes that must be compatible with any blueprint bundle for which this namespace 
     * handler is to apply or <code>null</code> if no compatibility checks are to be performed
     */
    Set<Class> getManagedClasses();
    
    /**
     * Parse a stand-alone blueprint component 
     *
     * Given an <code>Element</code> node as a root, this method parses the stand-alone component and returns its
     * metadata. The supplied <code>ParserContext</code> should be used to parse embedded blueprint elements as well
     * as creating metadata.
     * 
     * @param element The DOM element representing the custom component
     * @param context The <code>ParserContext</code> for parsing sub-components and creating metadata objects
     * @return A metadata instance representing the custom component. This should be an instance of an appropriate
     * <code>MutableMetadata</code> type to enable further decoration by other namespace handlers
     */
    Metadata parse(Element element, ParserContext context);
    
    /**
     * Process a child node of an enclosing blueprint component. 
     * 
     * If the decorator method returns a new <code>ComponentMetadata</code> instance, this will replace the argument 
     * <code>ComponentMetadata</code> in subsequent parsing and namespace handler invocations. A namespace
     * handler that elects to return a new <code>ComponentMetadata</code> instance should
     * ensure that existing interceptors are registered against the new instance if appropriate.
     * 
     * Due to the interaction with interceptors, a namespace handler should prefer to change a component metadata
     * instead of returning a new instance wherever possible. This can be achieved by casting a 
     * <code>ComponentMetadata</code> to its corresponding <code>MutabableComponentMetadata</code> instance.
     * Note however that a given <code>ComponentMetadata</code> instance cannot be guaranteed to implement
     * the mutable interface if it was constructed by an agent other than the blueprint extender.
     * 
     * @param node The node associated with this NamespaceHandler that should be used to decorate the enclosing 
     * component
     * @param component The enclosing blueprint component
     * @param context The parser context
     * @return The decorated component to be used instead of the original enclosing component. This can of course be
     * the original component.
     */
    ComponentMetadata decorate(Node node, ComponentMetadata component, ParserContext context);
             
}