Fork me on GitHub

Cache Configuration Namespaces

Prerequisite Knowledge

To fully understand how Cache Configuration XML Namespaces are declared when using an ExtensibleEnvironment, you need a solid understanding of XML Namespaces.

Rather than (re)creating a tutorial on the definition and use of XML Namespaces here, we're going to point you to the Internet where there are some really good introductions.

Consequently as a pre-condition to reading the rest of this document, we advise you read one or more of the following:

XML Namespaces in Cache Configurations

The first thing to understand about the use of XML Namespaces in Coherence Cache Configurations is that they must completely adhere to the XML specification.
That is, the ExtensibleEnvironment implementation expects both the syntax of XML elements using namespaces and the declaration of said XML Namespaces with in an Cache Configuration are valid. Further, the ExtensibleEnvironment implementation performs checks to ensure that XML elements making use of XML Namespaces are valid and the prefixes used each have a corresponding XMLns declaration and if not, fails-fast.

The only special treatment given to the use of XML Namespaces in a Cache Configuration is to the meaning of the URIs specified in the XML Namespace declarations. Here it is expected that the URIs be of the format "class://FullyQualifiedClassName" and if not, the ExtensibleEnvironment will fail-fast.

Much like Apache Ant's use of antlibs, the ExtensibleEnvironment uses the URIs specified in XML Namespace declarations to dynamically load appropriate namespace handler implementations, in this case classes that implement the NamespaceContentHandler interface, each of which may be used to independently process associated XML elements (and attributes) as they occur with in a Cache Configuration.

For example in the following Cache Configuration file the ExtensibleEnvironment will dynamically load and instantiate the class RunNamespaceContentHandler (which must implement the NamespaceContentHandler interface) to handle XML content (elements and attributes) that are prefixed with the namespace "run". More specifically, during the processing of the XML DOM for the Cache Configuration, all XML elements (and attributes) occurring with in the "run" namespace will be passed to the associated RunNamespaceContentHandler instance for handling.

<cache-config xmlns:run="class://RunNamespaceContentHandler">

   <run:runnable classname="MyRunnable" every="10m"/>

   ... regular cache configuration ...

</cache-config>

IMPORTANT

  1. Should a declared URI class fail to implement the NamespaceContentHandler interface, the processing of the Cache Configuration will fail-fast with an error.

  2. Should an attempt be made to use XML content (elements or attributes) with a prefix that is undefined, the processing of the Cache Configuration will fail-fast with an error.

  3. Should an attempt be made to redefine the default NamespaceContentHandler, the processing of the Cache Configuration will fail-fast with an error.
    In the current implementation the default namespace is reserved for Coherence.

Built-in Namespace Content Handlers

Out-of-the box, Coherence Incubator Common provides several NamespaceContentHandler implementations. The reference documentation for each is provided below.

The following XML Cache Configuration Namespaces are provided by the Coherence Incubator Common Package.

  • The Coherence Namespace: The default and implicitly defined namespace for processing Coherence Cache Configuration elements.

  • The Filter Namespace: A utility namespace providing the ability to define Coherence Filters in Cache Configurations.

  • The Element Namespace: A namespace enabling runtime transformation of XML elements in a cache configuration. ie: provides <cache-config element:introduce-cache-config="..."> and other functionality.

  • The Instance Namespace (deprecated): A utility namespace providing the ability to specify how custom classes may be instantiated.

  • The Value Namespace (deprecated): A utility namespace providing the ability to define strongly typed values.