content: /**
   *  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.osgi.service.blueprint.reflect.ComponentMetadata;
  import org.osgi.service.blueprint.reflect.Metadata;
  import org.w3c.dom.Element;
  import org.w3c.dom.Node;
  
  /**
   * 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);
               
  }
  