Since version 2.0, Spring has featured a mechanism for schema-based extensions to the basic Spring XML format for defining and configuring beans. This section is devoted to detailing how you would go about writing your own custom XML bean definition parsers and integrating such parsers into the Spring IoC container.

To facilitate the authoring of configuration files using a schema-aware XML editor, Spring's extensible XML configuration mechanism is based on XML Schema. If you are not familiar with Spring's current XML configuration extensions that come with the standard Spring distribution, please first read the appendix entitled Appendix A, XML Schema-based configuration.

Creating new XML configuration extensions can be done by following a (relatively) simple process of authoring an XML schema, coding a NamespaceHandler implementation, coding one or more BeanDefinitionParser instances and registering the NamespaceHandler and the schema in a dedicated properties file. What follows is a description of each of these steps. In the example, we'll create an XML extension (a custom XML element) that allows us to configure objects of type SimpleDateFormat directly in a Spring IoC container.

Creating an XML configuration extension for use with Spring's IoC container starts with authoring an XML Schema to describe the extension. What follows is the schema we'll use to configure SimpleDateFormat objects. The emphasized line contains an extension base for all tags that will be identifiable (meaning they have an id attribute that will be used as the bean identifier in the container).

#### myns.xsd (inside package org/springframework/samples/xml)

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://www.springframework.org/schema/myns"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:beans="http://www.springframework.org/schema/beans"
    targetNamespace="http://www.mycompany.com/schema/myns"
    elementFormDefault="qualified"
    attributeFormDefault="unqualified">

   <xsd:import namespace="http://www.springframework.org/schema/beans"/>
   
   <xsd:element name="dateformat">
      <xsd:complexType>
         <xsd:complexContent>
            <xsd:extension base="beans:identifiedType">
               <xsd:attribute name="lenient" type="xsd:boolean"/>
               <xsd:attribute name="pattern" type="xsd:string" use="required"/>
            </xsd:extension>
         </xsd:complexContent>
      </xsd:complexType>
   </xsd:element>
   
</xsd:schema>

The above schema will be used to configure SimpleDateFormat objects, directly in an XML application context file using the myns:dateformat configuration directive. As noted above, the id attribute will (in this case) be used as the bean identifier for the SimpleDateFormat bean.

<myns:dateformat id="dateFormat" 
    pattern="yyyy-MM-dd HH:mm"
    lenient="true"/>

Note that after we've created the infrastructure classes, the above snippet of XML will essentially be exactly the same as the following XML snippet. In other words, we're just creating a bean in the container, identified by dateFormat of type SimpleDateFormat, with a couple of properties set.

<bean id="dateFormat" class="java.text.SimpleDateFormat">
    <constructor-arg value="yyyy-HH-dd HH:mm"/>
    <property name="lenient" value="true"/>
</bean>

	Note
	The schema-based approach to creating configuration format, allows for tight integration with an IDE that has a schema-aware XML editor. Using a properly authored schema, you can for example use autocompletion to have a user choose between several configuration options defined in the enumeration.

In addition to the schema, we need a NamespaceHandler that will parse all elements of this specific namespace Spring encounters while parsing configuration files. The NamespaceHandler should in our case take care of the parsing of the myns:dateformat element.

The NamespaceHandler interface is pretty simple in that it only features three methods:

Although it is perfectly possible to code your own NamespaceHandler for the entire namespace (and hence provide code that parses each and every element in the namespace), it is often the case that each top-level XML element in a Spring XML configuration file results in a single bean definition (as in our case, where the myns:dateformat element results in a SimpleDateFormat bean definition). Spring features a couple of convenience classes that support this scenario. In this example, we'll use the most often used convenience class which is the NamespaceHandlerSupport class:

package org.springframework.samples.xml;

import org.springframework.beans.factory.xml.NamespaceHandlerSupport;

public class MyNamespaceHandler extends NamespaceHandlerSupport {
    
    public void init() {
        registerBeanDefinitionParser("dateformat", 
                new SimpleDateFormatBeanDefinitionParser());        
    }
}

As you can see, the namespace handler shown above registers so-called BeanDefinitionParsers. A BeanDefinitionParser in this case will be consulted if the namespace handler encounters an XML element of the type that has been mapped to this specific bean definition parser (which is dateformat in this case). In other words, the BeanDefinitionParser is responsible for parsing one distinct top-level XML element defined in the schema. In the parser, we'll have access to the XML element (and its subelements) and the ParserContext. The latter can be used to obtain a reference to the BeanDefinitionRegistry, for instance, as seen in the example below.

package org.springframework.samples.xml;

import java.text.SimpleDateFormat;

import org.springframework.beans.factory.config.BeanDefinition;
import org.springframework.beans.factory.config.BeanDefinitionHolder;
import org.springframework.beans.factory.support.BeanDefinitionReaderUtils;
import org.springframework.beans.factory.support.RootBeanDefinition;
import org.springframework.beans.factory.xml.BeanDefinitionParser;
import org.springframework.beans.factory.xml.ParserContext;
import org.springframework.util.StringUtils;
import org.w3c.dom.Element;

public class SimpleDateFormatBeanDefinitionParser implements BeanDefinitionParser {
   
   public BeanDefinition parse(Element element, ParserContext parserContext) {
      
      // create a RootBeanDefinition that will serve as configuration
      // holder for the 'pattern' attribute and the 'lenient' attribute
      RootBeanDefinition beanDef = new RootBeanDefinition();
      beanDef.setBeanClass(SimpleDateFormat.class);      

      // never null since the schema requires it 
      String pattern = element.getAttribute("pattern");
      beanDef.getConstructorArgumentValues().addGenericArgumentValue(pattern);

      String lenientString = element.getAttribute("lenient");
      if (StringUtils.hasText(lenientString)) {
         // won't throw exception if validation is turned on (boolean type set in schema)         
         beanDef.getPropertyValues().addPropertyValue("lenient", new Boolean(lenientString));
      }
      
      // retrieve the ID attribute that will serve as the bean identifier in the context 
      String id = element.getAttribute("id");
      
      // create a bean definition holder to be able to register the
      // bean definition with the bean definition registry
      // (obtained through the ParserContext)
      BeanDefinitionHolder holder = new BeanDefinitionHolder(beanDef, id);
      
      // register the BeanDefinitionHolder (which contains the bean definition)
      // with the BeanDefinitionRegistry
      BeanDefinitionReaderUtils.registerBeanDefinition(holder, parserContext.getRegistry());
      
      return beanDef;
   }
}

	Note
	In the example here, we're defining a BeanDefinition and registering it with the BeanDefinitionRegistry. Note that you don't necessarily have to register a bean definition with the registry or return a bean definition from the parse() method. You are free to do whatever you want with the information given to you (i.e. the XML element) and the ParserContext.

The ParserContext provides access to following properties:

We're done implementing the NamespaceHandler and the BeanDefinitionParser that will take care of parsing the custom XML Schema for us. We now have the following artifacts:

The last thing we need to do is to get the namespace ready for use by registering it in two special purpose properties files. These properties files are both placed in the META-INF directory and can, for example, be distributed alongside your binary classes in a JAR file. Spring will automatically pick up the new namespaces and handlers once it finds the properties files on the classpath.

http\://www.mycompany.com/schema/myns=org.springframework.samples.xml.MyNamespaceHandler

http\://www.mycompany.com/schema/myns/myns.xsd=org/springframework/samples/xml/myns.xsd