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

org.springframework.beans.factory.xml

## Class AbstractBeanDefinitionParser

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

- All Implemented Interfaces:
    BeanDefinitionParser
  Direct Known Subclasses:
    AbstractSingleBeanDefinitionParser

      public abstract class AbstractBeanDefinitionParser
      extends Object
      implements BeanDefinitionParser

  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 `BeanDefinitions`. 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`.

  Since:
    2.0
  Author:
    Rob Harrop, Juergen Hoeller, Rick Evans, Dave Syer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `ID_ATTRIBUTE` Constant for the id attribute
    `static String` | `NAME_ATTRIBUTE` Constant for the name attribute

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractBeanDefinitionParser()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `BeanDefinition` | `parse(Element element, ParserContext parserContext)` Parse the specified `Element` and register the resulting `BeanDefinition(s)` with the `BeanDefinitionRegistry` embedded in the supplied `ParserContext`.
    `protected abstract AbstractBeanDefinition` | `parseInternal(Element element, ParserContext parserContext)` Central template method to actually parse the supplied `Element` into one or more `BeanDefinitions`.
    `protected void` | `postProcessComponentDefinition(BeanComponentDefinition componentDefinition)` Hook method called after the primary parsing of a `BeanComponentDefinition` but before the `BeanComponentDefinition` has been registered with a `BeanDefinitionRegistry`.
    `protected void` | `registerBeanDefinition(BeanDefinitionHolder definition, BeanDefinitionRegistry registry)` Register the supplied `bean` with the supplied `registry`.
    `protected String` | `resolveId(Element element, AbstractBeanDefinition definition, ParserContext parserContext)` Resolve the ID for the supplied `BeanDefinition`.
    `protected boolean` | `shouldFireEvents()` Controls whether this parser is supposed to fire a `BeanComponentDefinition` event after parsing the bean definition.
    `protected boolean` | `shouldGenerateId()` Should an ID be generated instead of read from the passed in `Element`?
    `protected boolean` | `shouldGenerateIdAsFallback()` Should an ID be generated instead if the passed in `Element` does not specify an "id" attribute explicitly?

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

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

- - ### Field Detail

    - #### ID_ATTRIBUTE

          public static final String ID_ATTRIBUTE

      Constant for the id attribute
      See Also:
        Constant Field Values

    - #### NAME_ATTRIBUTE

          public static final String NAME_ATTRIBUTE

      Constant for the name attribute
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AbstractBeanDefinitionParser

          public AbstractBeanDefinitionParser()

  - ### Method Detail

    - #### parse

          public final BeanDefinition parse(Element element,
                             ParserContext parserContext)

      Description copied from interface: `BeanDefinitionParser`
      Parse the specified `Element` and register the resulting `BeanDefinition(s)` with the `BeanDefinitionRegistry` embedded in the supplied `ParserContext`.

      Implementations must return the primary `BeanDefinition` that results from the parse if they will ever be used in a nested fashion (for example as an inner tag in a `<property/>` tag). Implementations may return `null` if they will not be used in a nested fashion.

      Specified by:
        `parse` in interface `BeanDefinitionParser`
      Parameters:
        `element` - the element that is to be parsed into one or more `BeanDefinitions`
        `parserContext` - the object encapsulating the current state of the parsing process; provides access to a `BeanDefinitionRegistry`
      Returns:
        the primary `BeanDefinition`

    - #### resolveId

          protected String resolveId(Element element,
                         AbstractBeanDefinition definition,
                         ParserContext parserContext)
                              throws BeanDefinitionStoreException

      Resolve the ID for the supplied `BeanDefinition`.

      When using `generation`, a name is generated automatically. Otherwise, the ID is extracted from the "id" attribute, potentially with a `fallback` to a generated id.

      Parameters:
        `element` - the element that the bean definition has been built from
        `definition` - the bean definition to be registered
        `parserContext` - the object encapsulating the current state of the parsing process; provides access to a `BeanDefinitionRegistry`
      Returns:
        the resolved id
      Throws:
        `BeanDefinitionStoreException` - if no unique name could be generated for the given bean definition

    - #### registerBeanDefinition

          protected void registerBeanDefinition(BeanDefinitionHolder definition,
                                    BeanDefinitionRegistry registry)

      Register the supplied `bean` with the supplied `registry`.

      Subclasses can override this method to control whether or not the supplied `bean` is actually even registered, or to register even more beans.

      The default implementation registers the supplied `bean` with the supplied `registry` only if the `isNested` parameter is `false`, because one typically does not want inner beans to be registered as top level beans.

      Parameters:
        `definition` - the bean definition to be registered
        `registry` - the registry that the bean is to be registered with
      See Also:
        `BeanDefinitionReaderUtils.registerBeanDefinition(BeanDefinitionHolder, BeanDefinitionRegistry)`

    - #### parseInternal

          protected abstract AbstractBeanDefinition parseInternal(Element element,
                                             ParserContext parserContext)

      Central template method to actually parse the supplied `Element` into one or more `BeanDefinitions`.
      Parameters:
        `element` - the element that is to be parsed into one or more `BeanDefinitions`
        `parserContext` - the object encapsulating the current state of the parsing process; provides access to a `BeanDefinitionRegistry`
      Returns:
        the primary `BeanDefinition` resulting from the parsing of the supplied `Element`
      See Also:
        `parse(org.w3c.dom.Element, ParserContext)`, `postProcessComponentDefinition(org.springframework.beans.factory.parsing.BeanComponentDefinition)`

    - #### shouldGenerateId

          protected boolean shouldGenerateId()

      Should an ID be generated instead of read from the passed in `Element`?

      Disabled by default; subclasses can override this to enable ID generation. Note that this flag is about always generating an ID; the parser won't even check for an "id" attribute in this case.

      Returns:
        whether the parser should always generate an id

    - #### shouldGenerateIdAsFallback

          protected boolean shouldGenerateIdAsFallback()

      Should an ID be generated instead if the passed in `Element` does not specify an "id" attribute explicitly?

      Disabled by default; subclasses can override this to enable ID generation as fallback: The parser will first check for an "id" attribute in this case, only falling back to a generated ID if no value was specified.

      Returns:
        whether the parser should generate an id if no id was specified

    - #### shouldFireEvents

          protected boolean shouldFireEvents()

      Controls whether this parser is supposed to fire a `BeanComponentDefinition` event after parsing the bean definition.

      This implementation returns `true` by default; that is, an event will be fired when a bean definition has been completely parsed. Override this to return `false` in order to suppress the event.

      Returns:
        `true` in order to fire a component registration event after parsing the bean definition; `false` to suppress the event
      See Also:
        `postProcessComponentDefinition(org.springframework.beans.factory.parsing.BeanComponentDefinition)`, `ReaderContext.fireComponentRegistered(org.springframework.beans.factory.parsing.ComponentDefinition)`

    - #### postProcessComponentDefinition

          protected void postProcessComponentDefinition(BeanComponentDefinition componentDefinition)

      Hook method called after the primary parsing of a `BeanComponentDefinition` but before the `BeanComponentDefinition` has been registered with a `BeanDefinitionRegistry`.

      Derived classes can override this method to supply any custom logic that is to be executed after all the parsing is finished.

      The default implementation is a no-op.

      Parameters:
        `componentDefinition` - the `BeanComponentDefinition` that is to be processed