org.apache.aries.blueprint.NamespaceHandler Maven / Gradle / Ivy

Go to download
/**
 *  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 
 * osgi.service.blueprint.namespace service property denoting the namespace URIs this
 * handler can process. The service property value can be either a single String or URI, 
 * or a Collection respectively array of String or URI.
 * 
 * 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 parse method 
 * to create the Metadata for the xml element while for an element that is part
 * of an existing component the parser will invoke the decorated method to augment
 * the enclosing ComponentMetadata instance.  Various utilities to interact with 
 * the blueprint parser are available to a namespace handler via the ParserContext argument 
 * passed to parse and decorate.
 * 
 * Recommended behaviour:
 * 
 * New metadata objects should be created via calling ParserContext.createMetadata(..) and
 * casting the returned object to the appropriate MutableComponentMetadata interface. 
 * This method ensures that the metadata object implements the interfaces necessary for other namespace handlers
 * to be able to use the metadata object.

 * Also, to prevent id clashes, component ids should be generated by calling ParserContext.generateId().
 * 
 * A namespace handler should not return new metadata instances from the decorate method if 
 * the same result could also be achieved by operating on a MutableComponentMetadata instance.
 * 
 * A namespace handler should not assume the existence of predefined entries in the component definition
 * registry such as blueprintBundle or blueprintBundleContext. 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
 * 
 * 
 */
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 Set of classes that must be compatible with any blueprint bundle for which this namespace 
     * handler is to apply or null if no compatibility checks are to be performed
     */
    Set getManagedClasses();
    
    /**
     * Parse a stand-alone blueprint component 
     *
     * Given an Element node as a root, this method parses the stand-alone component and returns its
     * metadata. The supplied ParserContext 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 ParserContext for parsing sub-components and creating metadata objects
     * @return A metadata instance representing the custom component. This should be an instance of an appropriate
     * MutableMetadata 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 ComponentMetadata instance, this will replace the argument 
     * ComponentMetadata in subsequent parsing and namespace handler invocations. A namespace
     * handler that elects to return a new ComponentMetadata 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 
     * ComponentMetadata to its corresponding MutabableComponentMetadata instance.
     * Note however that a given ComponentMetadata 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);
             
}