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

org.springframework.beans.factory.xml

## Class XmlBeanDefinitionReader

- java.lang.Object
- - org.springframework.beans.factory.support.AbstractBeanDefinitionReader
  - - org.springframework.beans.factory.xml.XmlBeanDefinitionReader

- All Implemented Interfaces:
    BeanDefinitionReader, EnvironmentCapable

      public class XmlBeanDefinitionReader
      extends AbstractBeanDefinitionReader

  Bean definition reader for XML bean definitions. Delegates the actual XML document reading to an implementation of the `BeanDefinitionDocumentReader` interface.

  Typically applied to a `DefaultListableBeanFactory` or a `GenericApplicationContext`.

  This class loads a DOM document and applies the BeanDefinitionDocumentReader to it. The document reader will register each bean definition with the given bean factory, talking to the latter's implementation of the `BeanDefinitionRegistry` interface.

  Since:
    26.11.2003
  Author:
    Juergen Hoeller, Rob Harrop, Chris Beams
  See Also:
    `setDocumentReaderClass(java.lang.Class<?>)`, `BeanDefinitionDocumentReader`, `DefaultBeanDefinitionDocumentReader`, `BeanDefinitionRegistry`, `DefaultListableBeanFactory`, `GenericApplicationContext`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `VALIDATION_AUTO` Indicates that the validation mode should be detected automatically.
    `static int` | `VALIDATION_DTD` Indicates that DTD validation should be used.
    `static int` | `VALIDATION_NONE` Indicates that the validation should be disabled.
    `static int` | `VALIDATION_XSD` Indicates that XSD validation should be used.

    - ### Fields inherited from class org.springframework.beans.factory.support.AbstractBeanDefinitionReader

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XmlBeanDefinitionReader(BeanDefinitionRegistry registry)` Create new XmlBeanDefinitionReader for the given bean factory.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected BeanDefinitionDocumentReader` | `createBeanDefinitionDocumentReader()` Create the `BeanDefinitionDocumentReader` to use for actually reading bean definitions from an XML document.
    `protected NamespaceHandlerResolver` | `createDefaultNamespaceHandlerResolver()` Create the default implementation of `NamespaceHandlerResolver` used if none is specified.
    `protected XmlReaderContext` | `createReaderContext(Resource resource)` Create the `XmlReaderContext` to pass over to the document reader.
    `protected int` | `detectValidationMode(Resource resource)` Detects which kind of validation to perform on the XML file identified by the supplied `Resource`.
    `protected int` | `doLoadBeanDefinitions(InputSource inputSource, Resource resource)` Actually load bean definitions from the specified XML file.
    `protected EntityResolver` | `getEntityResolver()` Return the EntityResolver to use, building a default resolver if none specified.
    `int` | `getValidationMode()` Return the validation mode to use.
    `protected int` | `getValidationModeForResource(Resource resource)` Gets the validation mode for the specified `Resource`.
    `boolean` | `isNamespaceAware()` Return whether or not the XML parser should be XML namespace aware.
    `int` | `loadBeanDefinitions(EncodedResource encodedResource)` Load bean definitions from the specified XML file.
    `int` | `loadBeanDefinitions(InputSource inputSource)` Load bean definitions from the specified XML file.
    `int` | `loadBeanDefinitions(InputSource inputSource, String resourceDescription)` Load bean definitions from the specified XML file.
    `int` | `loadBeanDefinitions(Resource resource)` Load bean definitions from the specified XML file.
    `int` | `registerBeanDefinitions(Document doc, Resource resource)` Register the bean definitions contained in the given DOM document.
    `void` | `setDocumentLoader(DocumentLoader documentLoader)` Specify the `DocumentLoader` to use.
    `void` | `setDocumentReaderClass(Class<?> documentReaderClass)` Specify the `BeanDefinitionDocumentReader` implementation to use, responsible for the actual reading of the XML bean definition document.
    `void` | `setEntityResolver(EntityResolver entityResolver)` Set a SAX entity resolver to be used for parsing.
    `void` | `setErrorHandler(ErrorHandler errorHandler)` Set an implementation of the `org.xml.sax.ErrorHandler` interface for custom handling of XML parsing errors and warnings.
    `void` | `setEventListener(ReaderEventListener eventListener)` Specify which `ReaderEventListener` to use.
    `void` | `setNamespaceAware(boolean namespaceAware)` Set whether or not the XML parser should be XML namespace aware.
    `void` | `setNamespaceHandlerResolver(NamespaceHandlerResolver namespaceHandlerResolver)` Specify the `NamespaceHandlerResolver` to use.
    `void` | `setProblemReporter(ProblemReporter problemReporter)` Specify which `ProblemReporter` to use.
    `void` | `setSourceExtractor(SourceExtractor sourceExtractor)` Specify the `SourceExtractor` to use.
    `void` | `setValidating(boolean validating)` Set whether to use XML validation.
    `void` | `setValidationMode(int validationMode)` Set the validation mode to use.
    `void` | `setValidationModeName(String validationModeName)` Set the validation mode to use by name.

    - ### Methods inherited from class org.springframework.beans.factory.support.AbstractBeanDefinitionReader

      `getBeanClassLoader, getBeanFactory, getBeanNameGenerator, getEnvironment, getRegistry, getResourceLoader, loadBeanDefinitions, loadBeanDefinitions, loadBeanDefinitions, loadBeanDefinitions, setBeanClassLoader, setBeanNameGenerator, setEnvironment, setResourceLoader`

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

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

- - ### Field Detail

    - #### VALIDATION_NONE

          public static final int VALIDATION_NONE

      Indicates that the validation should be disabled.
      See Also:
        Constant Field Values

    - #### VALIDATION_AUTO

          public static final int VALIDATION_AUTO

      Indicates that the validation mode should be detected automatically.
      See Also:
        Constant Field Values

    - #### VALIDATION_DTD

          public static final int VALIDATION_DTD

      Indicates that DTD validation should be used.
      See Also:
        Constant Field Values

    - #### VALIDATION_XSD

          public static final int VALIDATION_XSD

      Indicates that XSD validation should be used.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XmlBeanDefinitionReader

          public XmlBeanDefinitionReader(BeanDefinitionRegistry registry)

      Create new XmlBeanDefinitionReader for the given bean factory.
      Parameters:
        `registry` - the BeanFactory to load bean definitions into, in the form of a BeanDefinitionRegistry

  - ### Method Detail

    - #### setValidating

          public void setValidating(boolean validating)

      Set whether to use XML validation. Default is `true`.

      This method switches namespace awareness on if validation is turned off, in order to still process schema namespaces properly in such a scenario.

      See Also:
        `setValidationMode(int)`, `setNamespaceAware(boolean)`

    - #### setValidationModeName

          public void setValidationModeName(String validationModeName)

      Set the validation mode to use by name. Defaults to `VALIDATION_AUTO`.
      See Also:
        `setValidationMode(int)`

    - #### setValidationMode

          public void setValidationMode(int validationMode)

      Set the validation mode to use. Defaults to `VALIDATION_AUTO`.

      Note that this only activates or deactivates validation itself. If you are switching validation off for schema files, you might need to activate schema namespace support explicitly: see `setNamespaceAware(boolean)`.

    - #### getValidationMode

          public int getValidationMode()

      Return the validation mode to use.

    - #### setNamespaceAware

          public void setNamespaceAware(boolean namespaceAware)

      Set whether or not the XML parser should be XML namespace aware. Default is "false".

      This is typically not needed when schema validation is active. However, without validation, this has to be switched to "true" in order to properly process schema namespaces.

    - #### isNamespaceAware

          public boolean isNamespaceAware()

      Return whether or not the XML parser should be XML namespace aware.

    - #### setProblemReporter

          public void setProblemReporter(ProblemReporter problemReporter)

      Specify which `ProblemReporter` to use.

      The default implementation is `FailFastProblemReporter` which exhibits fail fast behaviour. External tools can provide an alternative implementation that collates errors and warnings for display in the tool UI.

    - #### setEventListener

          public void setEventListener(ReaderEventListener eventListener)

      Specify which `ReaderEventListener` to use.

      The default implementation is EmptyReaderEventListener which discards every event notification. External tools can provide an alternative implementation to monitor the components being registered in the BeanFactory.

    - #### setSourceExtractor

          public void setSourceExtractor(SourceExtractor sourceExtractor)

      Specify the `SourceExtractor` to use.

      The default implementation is `NullSourceExtractor` which simply returns `null` as the source object. This means that - during normal runtime execution - no additional source metadata is attached to the bean configuration metadata.

    - #### setNamespaceHandlerResolver

          public void setNamespaceHandlerResolver(NamespaceHandlerResolver namespaceHandlerResolver)

      Specify the `NamespaceHandlerResolver` to use.

      If none is specified, a default instance will be created through `createDefaultNamespaceHandlerResolver()`.

    - #### setDocumentLoader

          public void setDocumentLoader(DocumentLoader documentLoader)

      Specify the `DocumentLoader` to use.

      The default implementation is `DefaultDocumentLoader` which loads `Document` instances using JAXP.

    - #### setEntityResolver

          public void setEntityResolver(EntityResolver entityResolver)

      Set a SAX entity resolver to be used for parsing.

      By default, `ResourceEntityResolver` will be used. Can be overridden for custom entity resolution, for example relative to some specific base path.

    - #### getEntityResolver

          protected EntityResolver getEntityResolver()

      Return the EntityResolver to use, building a default resolver if none specified.

    - #### setErrorHandler

          public void setErrorHandler(ErrorHandler errorHandler)

      Set an implementation of the `org.xml.sax.ErrorHandler` interface for custom handling of XML parsing errors and warnings.

      If not set, a default SimpleSaxErrorHandler is used that simply logs warnings using the logger instance of the view class, and rethrows errors to discontinue the XML transformation.

      See Also:
        `SimpleSaxErrorHandler`

    - #### setDocumentReaderClass

          public void setDocumentReaderClass(Class<?> documentReaderClass)

      Specify the `BeanDefinitionDocumentReader` implementation to use, responsible for the actual reading of the XML bean definition document.

      The default is `DefaultBeanDefinitionDocumentReader`.

      Parameters:
        `documentReaderClass` - the desired BeanDefinitionDocumentReader implementation class

    - #### loadBeanDefinitions

          public int loadBeanDefinitions(Resource resource)
                                  throws BeanDefinitionStoreException

      Load bean definitions from the specified XML file.
      Parameters:
        `resource` - the resource descriptor for the XML file
      Returns:
        the number of bean definitions found
      Throws:
        `BeanDefinitionStoreException` - in case of loading or parsing errors

    - #### loadBeanDefinitions

          public int loadBeanDefinitions(EncodedResource encodedResource)
                                  throws BeanDefinitionStoreException

      Load bean definitions from the specified XML file.
      Parameters:
        `encodedResource` - the resource descriptor for the XML file, allowing to specify an encoding to use for parsing the file
      Returns:
        the number of bean definitions found
      Throws:
        `BeanDefinitionStoreException` - in case of loading or parsing errors

    - #### loadBeanDefinitions

          public int loadBeanDefinitions(InputSource inputSource)
                                  throws BeanDefinitionStoreException

      Load bean definitions from the specified XML file.
      Parameters:
        `inputSource` - the SAX InputSource to read from
      Returns:
        the number of bean definitions found
      Throws:
        `BeanDefinitionStoreException` - in case of loading or parsing errors

    - #### loadBeanDefinitions

          public int loadBeanDefinitions(InputSource inputSource,
                                String resourceDescription)
                                  throws BeanDefinitionStoreException

      Load bean definitions from the specified XML file.
      Parameters:
        `inputSource` - the SAX InputSource to read from
        `resourceDescription` - a description of the resource (can be `null` or empty)
      Returns:
        the number of bean definitions found
      Throws:
        `BeanDefinitionStoreException` - in case of loading or parsing errors

    - #### doLoadBeanDefinitions

          protected int doLoadBeanDefinitions(InputSource inputSource,
                                  Resource resource)
                                       throws BeanDefinitionStoreException

      Actually load bean definitions from the specified XML file.
      Parameters:
        `inputSource` - the SAX InputSource to read from
        `resource` - the resource descriptor for the XML file
      Returns:
        the number of bean definitions found
      Throws:
        `BeanDefinitionStoreException` - in case of loading or parsing errors

    - #### getValidationModeForResource

          protected int getValidationModeForResource(Resource resource)

      Gets the validation mode for the specified `Resource`. If no explicit validation mode has been configured then the validation mode is `detected`.

      Override this method if you would like full control over the validation mode, even when something other than `VALIDATION_AUTO` was set.

    - #### detectValidationMode

          protected int detectValidationMode(Resource resource)

      Detects which kind of validation to perform on the XML file identified by the supplied `Resource`. If the file has a `DOCTYPE` definition then DTD validation is used otherwise XSD validation is assumed.

      Override this method if you would like to customize resolution of the `VALIDATION_AUTO` mode.

    - #### registerBeanDefinitions

          public int registerBeanDefinitions(Document doc,
                                    Resource resource)
                                      throws BeanDefinitionStoreException

      Register the bean definitions contained in the given DOM document. Called by `loadBeanDefinitions`.

      Creates a new instance of the parser class and invokes `registerBeanDefinitions` on it.

      Parameters:
        `doc` - the DOM document
        `resource` - the resource descriptor (for context information)
      Returns:
        the number of bean definitions found
      Throws:
        `BeanDefinitionStoreException` - in case of parsing errors
      See Also:
        `loadBeanDefinitions(org.springframework.core.io.Resource)`, `setDocumentReaderClass(java.lang.Class<?>)`, `BeanDefinitionDocumentReader.registerBeanDefinitions(org.w3c.dom.Document, org.springframework.beans.factory.xml.XmlReaderContext)`

    - #### createBeanDefinitionDocumentReader

          protected BeanDefinitionDocumentReader createBeanDefinitionDocumentReader()

      Create the `BeanDefinitionDocumentReader` to use for actually reading bean definitions from an XML document.

      The default implementation instantiates the specified "documentReaderClass".

      See Also:
        `setDocumentReaderClass(java.lang.Class<?>)`

    - #### createReaderContext

          protected XmlReaderContext createReaderContext(Resource resource)

      Create the `XmlReaderContext` to pass over to the document reader.

    - #### createDefaultNamespaceHandlerResolver

          protected NamespaceHandlerResolver createDefaultNamespaceHandlerResolver()

      Create the default implementation of `NamespaceHandlerResolver` used if none is specified. Default implementation returns an instance of `DefaultNamespaceHandlerResolver`.