org.apache.aries.blueprint

Interface NamespaceHandler

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:

• 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

Method Summary

Methods

Modifier and Type	Method and Description
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.