Namespace handlers process the elements and attributes that are used within an XML namespace. Namespace handlers can directly implement the NamespaceHandler interface. The interface relies on the DocumentPreprocessor, ElementProcessor, and AttributeProcessor interfaces. XML processing is performed within a processing context as defined by the ProcessingContext interface.

Elements and attributes that are encountered in a namespace must be processed by a processor implementation. Element and attribute processors are responsible for processing, parsing, and type conversion logic. Document preprocessors are used to mutate elements, if required, before they are processed.

Example 4-1 provides a basic NamespaceHandler implementation. The GreetingNamespaceHandler implementation processes a <message> element using an ElementProcessor implementation (MessageProcessor), which is included as an inner class. For the example, the following XML is assumed:

<?xml version="1.0"><cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config" 
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config 
      coherence-cache-config.xsd"
   xmlns:ex="class://com.examples.GreetingNamespaceHandler">

   <ex:message>hello</ex:message>
   ...

import com.tangosol.config.ConfigurationException;
import com.tangosol.config.xml.AttributeProcessor;
import com.tangosol.config.xml.DocumentPreprocessor;
import com.tangosol.config.xml.ElementProcessor;
import com.tangosol.config.xml.NamespaceHandler;
import com.tangosol.config.xml.ProcessingContext;
import com.tangosol.run.xml.XmlAttribute;
import com.tangosol.run.xml.XmlElement;
import java.net.URI;

public class GreetingNamespaceHandler implements NamespaceHandler
{
   public AttributeProcessor getAttributeProcessor(XmlAttribute xmlAttribute) 
   {
      return null;
   }
 
   public DocumentPreprocessor getDocumentPreprocessor()
   {
      return null;
   }
 
   public ElementProcessor getElementProcessor(XmlElement xmlElement)
   {
      if (xmlElement.getName().equals("ex:message"))
      {
         MessageProcessor  mp = new MessageProcessor();
         return mp;
      }
      else
      {
         throw new RuntimeException("Unknown element type " +
            xmlElement.getQualifiedName());
      }
   }

   public void onEndNamespace(ProcessingContext processingContext, 
      XmlElement xmlElement, String string, URI uRI) 
   {
   }
 
   public void onStartNamespace(ProcessingContext processingContext, 
      XmlElement xmlElement, String string, URI uRI) 
   {
   }

   public class MessageProcessor implements ElementProcessor
   {
      public Object process(ProcessingContext processingContext, 
         XmlElement xmlElement) throws ConfigurationException 
      {
         System.out.println("Greeting is: " + xmlElement.getString());
         return null;
      }
   }
}

The AbstractNamespaceHandler class provides a useful and extensible base implementation of the NamespaceHandler, ElementProcessor and AttributeProcessor interfaces together with mechanisms to register processors for specifically named elements and attributes. The class simplifies the processing of elements and attributes and can, in most cases, remove the requirement to directly implement the element and attribute processor interfaces.

This section contains the following topics:

• Registering Processors
  
• Using Injection to Process Element Content
  

The JNDI resource namespace handler is used at runtime to process <resource> elements that are found in a cache configuration file. The handler extends the AbstractNamespaceHandler class and registers the JndiBasedParameterizedBuilder class for the <resource> element. The following example shows the namespace handler definition.

import com.tangosol.coherence.config.builder.ParameterizedBuilder;
import com.tangosol.config.xml.AbstractNamespaceHandler;

public class JndiNamespaceHandler extends AbstractNamespaceHandler
{
    public JndiNamespaceHandler()
    {
        registerElementType("resource", JndiBasedParameterizedBuilder.class);
    }
}

The JndiBasedParameterizedBuilder class performs a JNDI context lookup to locate and create an object using the name and initialization parameters that are provided in the <resource-name> and <init-parms> elements, respectively. The setter methods for these elements (setResourceNameExpression and setParameterList) use the @Injectable annotation to pass the values configured in the cache configuration files.

import com.tangosol.coherence.config.ParameterList;
import com.tangosol.coherence.config.SimpleParameterList;
import com.tangosol.coherence.config.builder.ParameterizedBuilder;
import com.tangosol.coherence.config.builder.ParameterizedBuilder.
   ReflectionSupport;
import com.tangosol.config.annotation.Injectable;
import com.tangosol.config.expression.Expression;
import com.tangosol.config.expression.LiteralExpression;
import com.tangosol.config.expression.Parameter;
import com.tangosol.config.expression.ParameterResolver;
import com.tangosol.util.Base;
import java.util.Hashtable;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public class JndiBasedParameterizedBuilder implements
   ParameterizedBuilder<Object>, ReflectionSupport
{   private static final Logger logger =
      Logger.getLogger(JndiBasedParameterizedBuilder.class.getName());

   private Expression<String> m_exprResourceName;

   private ParameterList m_parameterList;

   public JndiBasedParameterizedBuilder()
   {
      m_exprResourceName = new LiteralExpression<String>("");
      m_parameterList = new SimpleParameterList();
   }
 
   public Expression<String> getResourceNameExpression()
   {
      return m_exprResourceName;
   }
 
   @Injectable("resource-name")
   public void setResourceNameExpression(Expression<String> exprResourceName)
   {
      m_exprResourceName = exprResourceName;
   }
 
   public ParameterList getParameterList()
   {
      return m_parameterList;
   }
 
   @Injectable("init-params")
   public void setParameterList(ParameterList parameterList)
   {
      m_parameterList = parameterList;
   }
 
   public boolean realizes(Class<?> clazz,
                           ParameterResolver parameterResolver,
                           ClassLoader classLoader)
   {
      return clazz.isAssignableFrom(realize(parameterResolver, classLoader,
         null).getClass());
    }
 
   public Object realize(ParameterResolver parameterResolver,
                         ClassLoader classLoader,
                         ParameterList parameterList)
   {
      InitialContext initialContext;
       try
      {
         String sResourceName = m_exprResourceName.evaluate(parameterResolver);
         Hashtable<String, Object> env = new Hashtable<String, Object>();

         for (Parameter parameter : m_parameterList)
         {
            env.put(parameter.getName(), parameter.evaluate(parameterResolver));
         }

         initialContext = new InitialContext(env);

         if (logger.isLoggable(Level.FINE))
         {
            logger.log(Level.FINE,
                       "Looking up {0} using JNDI with the environment {1}",
                        new Object[] {sResourceName, env});
         }

         Object resource = initialContext.lookup(sResourceName);

         if (logger.isLoggable(Level.FINE))
         {
            logger.log(Level.FINE, "Found {0} using JNDI", resource);
         }
 
         return resource;
      }
      catch (NamingException e)
      {
         throw Base.ensureRuntimeException(e, "Unable to resolve the JNDI
            resource: " + m_exprResourceName.toString());
      }
   }
 
   public String toString()
   {
      return String.format("%s{resourceName=%s, parameters=%s}",
                           this.getClass().getName(), m_exprResourceName,
                           m_parameterList);
   }
}

The JNDI resource namespace handler must be declared within the cache configuration file. Declare the namespace by providing the URI to the handler class and assigning a namespace prefix. Any prefix can be used. The following example uses jndi as the prefix:

<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd"
   xmlns:jndi="class://com.examples.JndiNamespaceHandler">
...

The JNDI resource namespace handler can be used whenever an application requires a resource to be located and created. In addition, the namespace can be used when defining custom implementations using the <class-scheme> or <instance> elements. Based on the handler implementation, the <resource> and <resource-name> element are required and the <init-params> element is optional.

The following example uses a JNDI resource for a cache store when defining a distributed scheme:

<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd"
   xmlns:jndi="class://com.examples.JndiNamespaceHandler">
...

   <caching-schemes>
      <distributed-scheme>
         <scheme-name>distributed-rwbm</scheme-name>
         <backing-map-scheme>
            <read-write-backing-map-scheme>
               <internal-cache-scheme>
                  <local-scheme/>
               </internal-cache-scheme>
               <cachestore-scheme>
                  <class-scheme>
                     <jndi:resource>
                        <jndi:resource-name>MyCacheStore</jndi:resource-name>
                        <init-params>
                           <init-param>
                              <param-type>java.lang.String</param-type>
                              <param-value>{cache-name}</param-value>
                           </init-param>
                        </init-params>
                     </jndi:resource>
                  </class-scheme>
               </cachestore-scheme>
            </read-write-backing-map-scheme>
         </backing-map-scheme>
      </distributed-scheme>
   <caching-schemes>
</cache-config>

The following example uses a JNDI resource to resolve a DNS record:

<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd"
   xmlns:jndi="class://com.examples.JndiNamespaceHandler">
...
<jndi:resource>
   <jndi:resource-name>dns:///www.oracle.com</jndi:resource-name>
</jndi:resource>

The following example uses a JNDI resource to resolve a JMS connection factory:

<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd"
   xmlns:jndi="class://com.examples.JndiNamespaceHandler">
...

<jndi:resource>
   <jndi:resource-name>ConnectionFactory</jndi:resource-name>
   <init-params>
      <init-param>
         <param-name>java.naming.factory.initial</param-name>
         <param-value>org.apache.activemq.jndi.ActiveMQInitialContextFactory
         </param-value>
      </init-param>
      <init-param>
         <param-name>java.naming.provider.url</param-name>
         <param-value system-property="java.naming.provider.url"></param-value>
      </init-param>
   </init-params>
</jndi:resource>