AbstractSimpleBeanDefinitionParser (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.beans.factory.xml

## Class AbstractSimpleBeanDefinitionParser

- java.lang.Object
- - org.springframework.beans.factory.xml.AbstractBeanDefinitionParser
  - - org.springframework.beans.factory.xml.AbstractSingleBeanDefinitionParser
    - - org.springframework.beans.factory.xml.AbstractSimpleBeanDefinitionParser

- All Implemented Interfaces:
    BeanDefinitionParser
  Direct Known Subclasses:
    CastorMarshallerBeanDefinitionParser

      public abstract class AbstractSimpleBeanDefinitionParser
      extends AbstractSingleBeanDefinitionParser

  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 `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 `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 `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 `&lt;util:properties/&gt;` element matches the `PropertiesLoaderSupport.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 `AbstractSingleBeanDefinitionParser.getBeanClass(org.w3c.dom.Element)` method to return the `PropertiesFactoryBean` type.

  Since:
    2.0
  Author:
    Rob Harrop, Rick Evans, Juergen Hoeller
  See Also:
    `Conventions.attributeNameToPropertyName(String)`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.beans.factory.xml.AbstractBeanDefinitionParser

      `ID_ATTRIBUTE, NAME_ATTRIBUTE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractSimpleBeanDefinitionParser()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `doParse(Element element, ParserContext parserContext, BeanDefinitionBuilder builder)` Parse the supplied `Element` and populate the supplied `BeanDefinitionBuilder` as required.
    `protected String` | `extractPropertyName(String attributeName)` Extract a JavaBean property name from the supplied attribute name.
    `protected boolean` | `isEligibleAttribute(Attr attribute)` Deprecated. in favour of `isEligibleAttribute(org.w3c.dom.Attr, ParserContext)`
    `protected boolean` | `isEligibleAttribute(Attr attribute, ParserContext parserContext)` Determine whether the given attribute is eligible for being turned into a corresponding bean property value.
    `protected boolean` | `isEligibleAttribute(String attributeName)` Determine whether the given attribute is eligible for being turned into a corresponding bean property value.
    `protected void` | `postProcess(BeanDefinitionBuilder beanDefinition, Element element)` Hook method that derived classes can implement to inspect/change a bean definition after parsing is complete.

    - ### Methods inherited from class org.springframework.beans.factory.xml.AbstractSingleBeanDefinitionParser

      `doParse, getBeanClass, getBeanClassName, getParentName, parseInternal`

    - ### Methods inherited from class org.springframework.beans.factory.xml.AbstractBeanDefinitionParser

      `parse, postProcessComponentDefinition, registerBeanDefinition, resolveId, shouldFireEvents, shouldGenerateId, shouldGenerateIdAsFallback`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### AbstractSimpleBeanDefinitionParser

          public AbstractSimpleBeanDefinitionParser()

  - ### Method Detail

    - #### doParse

          protected void doParse(Element element,
                     ParserContext parserContext,
                     BeanDefinitionBuilder builder)

      Parse the supplied `Element` and populate the supplied `BeanDefinitionBuilder` as required.

      This implementation maps any attributes present on the supplied element to `PropertyValue` instances, and `adds them` to the `builder`.

      The `extractPropertyName(String)` method is used to reconcile the name of an attribute with the name of a JavaBean property.

      Overrides:
        `doParse` in class `AbstractSingleBeanDefinitionParser`
      Parameters:
        `element` - the XML element being parsed
        `builder` - used to define the `BeanDefinition`
        `parserContext` - the object encapsulating the current state of the parsing process
      See Also:
        `extractPropertyName(String)`

    - #### isEligibleAttribute

          protected boolean isEligibleAttribute(Attr attribute,
                                    ParserContext parserContext)

      Determine whether the given attribute is eligible for being turned into a corresponding bean property value.

      The default implementation considers any attribute as eligible, except for the "id" attribute and namespace declaration attributes.

      Parameters:
        `attribute` - the XML attribute to check
        `parserContext` - the `ParserContext`
      See Also:
        `isEligibleAttribute(String)`

    - #### isEligibleAttribute

          @Deprecated
          protected boolean isEligibleAttribute(Attr attribute)

      Deprecated. in favour of `isEligibleAttribute(org.w3c.dom.Attr, ParserContext)`
      Determine whether the given attribute is eligible for being turned into a corresponding bean property value.

      The default implementation considers any attribute as eligible, except for the "id" attribute and namespace declaration attributes.

      Parameters:
        `attribute` - the XML attribute to check
      See Also:
        `isEligibleAttribute(String)`

    - #### isEligibleAttribute

          protected boolean isEligibleAttribute(String attributeName)

      Determine whether the given attribute is eligible for being turned into a corresponding bean property value.

      The default implementation considers any attribute as eligible, except for the "id" attribute.

      Parameters:
        `attributeName` - the attribute name taken straight from the XML element being parsed (never `null`)

    - #### extractPropertyName

          protected String extractPropertyName(String attributeName)

      Extract a JavaBean property name from the supplied attribute name.

      The default implementation uses the `Conventions.attributeNameToPropertyName(String)` method to perform the extraction.

      The name returned must obey the standard JavaBean property name conventions. For example for a class with a setter method '`setBingoHallFavourite(String)`', the name returned had better be '`bingoHallFavourite`' (with that exact casing).

      Parameters:
        `attributeName` - the attribute name taken straight from the XML element being parsed (never `null`)
      Returns:
        the extracted JavaBean property name (must never be `null`)

    - #### postProcess

          protected void postProcess(BeanDefinitionBuilder beanDefinition,
                         Element element)

      Hook method that derived classes can implement to inspect/change a bean definition after parsing is complete.

      The default implementation does nothing.

      Parameters:
        `beanDefinition` - the parsed (and probably totally defined) bean definition being built
        `element` - the XML element that was the source of the bean definition's metadata