org.apache.aries.blueprint
Interface NamespaceHandler

All Known Implementing Classes:
CmNamespaceHandler, ExtNamespaceHandler, NSHandlerOne, NSHandlerThree, NSHandlerTwo

public interface NamespaceHandler

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:


Method Summary
 ComponentMetadata decorate(org.w3c.dom.Node node, ComponentMetadata component, ParserContext context)
          Process a child node of an enclosing blueprint component.
 java.util.Set<java.lang.Class> getManagedClasses()
          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.
 java.net.URL getSchemaLocation(java.lang.String namespace)
          Retrieve a URL from where the schema for a given namespace can be retrieved
 Metadata parse(org.w3c.dom.Element element, ParserContext context)
          Parse a stand-alone blueprint component Given an Element node as a root, this method parses the stand-alone component and returns its metadata.
 

Method Detail

getSchemaLocation

java.net.URL getSchemaLocation(java.lang.String namespace)
Retrieve a URL from where the schema for a given namespace can be retrieved

Parameters:
namespace - The schema's namespace
Returns:
A URL that points to the location of the schema or null if the namespace validation is not needed

getManagedClasses

java.util.Set<java.lang.Class> getManagedClasses()
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).

Returns:
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

parse

Metadata parse(org.w3c.dom.Element element,
               ParserContext context)
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.

Parameters:
element - The DOM element representing the custom component
context - The ParserContext for parsing sub-components and creating metadata objects
Returns:
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

decorate

ComponentMetadata decorate(org.w3c.dom.Node node,
                           ComponentMetadata component,
                           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.

Parameters:
node - The node associated with this NamespaceHandler that should be used to decorate the enclosing component
component - The enclosing blueprint component
context - The parser context
Returns:
The decorated component to be used instead of the original enclosing component. This can of course be the original component.


Copyright © 2009-2011 The Apache Software Foundation. All Rights Reserved.