AbstractBeanDefinitionParser

Abstract BeanDefinitionParser implementation providing a number of convenience methods and a template method that subclasses must override to provide the actual parsing logic.

Use this BeanDefinitionParser implementation when you want to parse some arbitrarily complex XML into one or more BeanDefinition. If you just want to parse some XML into a single BeanDefinition, you may wish to consider the simpler convenience extensions of this class, namely AbstractSingleBeanDefinitionParser and AbstractSimpleBeanDefinitionParser.

AbstractSimpleBeanDefinitionParser

Convenient base class for when there exists a one-to-one mapping between attribute names on the element that is to be parsed and the property names on the Class being configured.

Extend this parser class when you want to create a single bean definition from a relatively simple custom XML element. The resulting BeanDefinition will be automatically registered with the relevant org.springframework.beans.factory.support.BeanDefinitionRegistry.

An example will hopefully make the use of this particular parser class immediately clear. Consider the following class definition:

public class SimpleCache implements Cache { public void setName(String name) {...} public void setTimeout(int timeout) {...} public void setEvictionPolicy(EvictionPolicy policy) {...} // remaining class definition elided for clarity... }

Then let us assume the following XML tag has been defined to permit the easy configuration of instances of the above class;

<caching:cache name="..." timeout="..." eviction-policy="..."/>

All that is required of the Java developer tasked with writing the parser to parse the above XML tag into an actual SimpleCache bean definition is the following:

public class SimpleCacheBeanDefinitionParser extends AbstractSimpleBeanDefinitionParser { protected Class getBeanClass(Element element) { return SimpleCache.class; } }

Please note that the AbstractSimpleBeanDefinitionParser is limited to populating the created bean definition with property values. if you want to parse constructor arguments and nested elements from the supplied XML element, then you will have to implement the #postProcess(org.springframework.beans.factory.support.BeanDefinitionBuilder, org.w3c.dom.Element) method and do such parsing yourself, or (more likely) subclass the AbstractSingleBeanDefinitionParser or AbstractBeanDefinitionParser classes directly.

The process of actually registering the SimpleCacheBeanDefinitionParser with the Spring XML parsing infrastructure is described in the Spring Framework reference documentation (in one of the appendices).

For an example of this parser in action (so to speak), do look at the source code for the org.springframework.beans.factory.xml.UtilNamespaceHandler.PropertiesBeanDefinitionParser; the observant (and even not so observant) reader will immediately notice that there is next to no code in the implementation. The PropertiesBeanDefinitionParser populates a org.springframework.beans.factory.config.PropertiesFactoryBean from an XML element that looks like this:

<util:properties location="jdbc.properties"/>

The observant reader will notice that the sole attribute on the <util:properties/> element matches the org.springframework.beans.factory.config.PropertiesFactoryBean#setLocation(org.springframework.core.io.Resource) method name on the PropertiesFactoryBean (the general usage thus illustrated holds true for any number of attributes). All that the PropertiesBeanDefinitionParser needs actually do is supply an implementation of the #getBeanClass(org.w3c.dom.Element) method to return the PropertiesFactoryBean type.

AbstractSingleBeanDefinitionParser

Base class for those BeanDefinitionParser implementations that need to parse and define just a single BeanDefinition.

Extend this parser class when you want to create a single bean definition from an arbitrarily complex XML element. You may wish to consider extending the AbstractSimpleBeanDefinitionParser when you want to create a single bean definition from a relatively simple custom XML element.

The resulting BeanDefinition will be automatically registered with the org.springframework.beans.factory.support.BeanDefinitionRegistry. Your job simply is to parse the custom XML Element into a single BeanDefinition.

BeanDefinitionDocumentReader

SPI for parsing an XML document that contains Spring bean definitions. Used by XmlBeanDefinitionReader for actually parsing a DOM document.

Instantiated per document to parse: implementations can hold state in instance variables during the execution of the registerBeanDefinitions method — for example, global settings that are defined for all bean definitions in the document.

BeansDtdResolver

EntityResolver implementation for the Spring beans DTD, to load the DTD from the Spring class path (or JAR file).

Fetches "spring-beans.dtd" from the class path resource "/org/springframework/beans/factory/xml/spring-beans.dtd", no matter whether specified as some local URL that includes "spring-beans" in the DTD name or as "http://www.springframework.org/dtd/spring-beans-2.0.dtd".

DefaultBeanDefinitionDocumentReader

Default implementation of the BeanDefinitionDocumentReader interface that reads bean definitions according to the "spring-beans" DTD and XSD format (Spring's default XML bean definition format).

The structure, elements, and attribute names of the required XML document are hard-coded in this class. (Of course a transform could be run if necessary to produce this format). <beans> does not need to be the root element of the XML document: this class will parse all bean definition elements in the XML file, regardless of the actual root element.

DefaultDocumentLoader

Spring's default DocumentLoader implementation.

Simply loads Document using the standard JAXP-configured XML parser. If you want to change the DocumentBuilder that is used to load documents, then one strategy is to define a corresponding Java system property when starting your JVM. For example, to use the Oracle DocumentBuilder, you might start your application like as follows:

java -Djavax.xml.parsers.DocumentBuilderFactory=oracle.xml.jaxp.JXDocumentBuilderFactory MyMainClass

DefaultNamespaceHandlerResolver

Default implementation of the NamespaceHandlerResolver interface. Resolves namespace URIs to implementation classes based on the mappings contained in mapping file.

By default, this implementation looks for the mapping file at META-INF/spring.handlers, but this can be changed using the #DefaultNamespaceHandlerResolver(ClassLoader, String) constructor.

DocumentDefaultsDefinition

Simple JavaBean that holds the defaults specified at the <beans> level in a standard Spring XML bean definition document: default-lazy-init, default-autowire, etc.

PluggableSchemaResolver

EntityResolver implementation that attempts to resolve schema URLs into local ClassPathResource using a set of mappings files.

By default, this class will look for mapping files in the classpath using the pattern: META-INF/spring.schemas allowing for multiple files to exist on the classpath at any one time. The format of META-INF/spring.schemas is a properties file where each line should be of the form systemId=schema-location where schema-location should also be a schema file in the classpath. Since systemId is commonly a URL, one must be careful to escape any ':' characters which are treated as delimiters in properties files.

The pattern for the mapping files can be overidden using the #PluggableSchemaResolver(ClassLoader, String) constructor

ResourceEntityResolver

EntityResolver implementation that tries to resolve entity references through a org.springframework.core.io.ResourceLoader (usually, relative to the resource base of an ApplicationContext), if applicable. Extends DelegatingEntityResolver to also provide DTD and XSD lookup.

Allows to use standard XML entities to include XML snippets into an application context definition, for example to split a large XML file into various modules. The include paths can be relative to the application context's resource base as usual, instead of relative to the JVM working directory (the XML parser's default).

Note: In addition to relative paths, every URL that specifies a file in the current system root, i.e. the JVM working directory, will be interpreted relative to the application context too.

SimpleConstructorNamespaceHandler

Simple NamespaceHandler implementation that maps custom attributes directly through to bean properties. An important point to note is that this NamespaceHandler does not have a corresponding schema since there is no way to know in advance all possible attribute names.

An example of the usage of this NamespaceHandler is shown below:

 <bean id="author" class="..TestBean" c:name="Enescu" c:work-ref="compositions"/> 

SimplePropertyNamespaceHandler

Simple NamespaceHandler implementation that maps custom attributes directly through to bean properties. An important point to note is that this NamespaceHandler does not have a corresponding schema since there is no way to know in advance all possible attribute names.

An example of the usage of this NamespaceHandler is shown below:

 <bean id="rob" class="..TestBean" p:name="Rob Harrop" p:spouse-ref="sally"/>

UtilNamespaceHandler

NamespaceHandler for the util namespace.

XmlBeanFactory

Convenience extension of DefaultListableBeanFactory that reads bean definitions from an XML document. Delegates to XmlBeanDefinitionReader underneath; effectively equivalent to using an XmlBeanDefinitionReader with a DefaultListableBeanFactory.

The structure, element and attribute names of the required XML document are hard-coded in this class. (Of course a transform could be run if necessary to produce this format). "beans" doesn't need to be the root element of the XML document: This class will parse all bean definition elements in the XML file.

This class registers each bean definition with the DefaultListableBeanFactory superclass, and relies on the latter's implementation of the BeanFactory interface. It supports singletons, prototypes, and references to either of these kinds of bean. See "spring-beans-3.x.xsd" (or historically, "spring-beans-2.0.dtd") for details on options and configuration style.

For advanced needs, consider using a DefaultListableBeanFactory with an XmlBeanDefinitionReader. The latter allows for reading from multiple XML resources and is highly configurable in its actual XML parsing behavior.

XmlReaderContext

Extension of org.springframework.beans.factory.parsing.ReaderContext, specific to use with an XmlBeanDefinitionReader. Provides access to the NamespaceHandlerResolver configured in the XmlBeanDefinitionReader.

XmlBeanDefinitionStoreException

XML-specific BeanDefinitionStoreException subclass that wraps a org.xml.sax.SAXException, typically a org.xml.sax.SAXParseException which contains information about the error location.