XMLValidateTask (Apache Ant API)
Date: 2018-07-10

org.apache.tools.ant.taskdefs.optional

## Class XMLValidateTask

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.optional.XMLValidateTask

- All Implemented Interfaces:
    java.lang.Cloneable
  Direct Known Subclasses:
    SchemaValidate

      public class XMLValidateTask
      extends Task

  Checks XML files are valid (or only well formed). The task uses the SAX2 parser implementation provided by JAXP by default (probably the one that is used by Ant itself), but one can specify any SAX1/2 parser if needed.

- - ### Property Summary

    All Methods Instance Methods Concrete Methods
    Type | Property and Description
    --- | ---
    `XMLValidateTask.Property` | `create` Creates a property.

  - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `XMLValidateTask.Attribute` The class to create to set a feature of the parser.
    `static class` | `XMLValidateTask.Property` A Parser property.
    `protected class` | `XMLValidateTask.ValidatorErrorHandler` ValidatorErrorHandler role : log SAX parse exceptions, remember if an error occurred

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Path` | `classpath`
    `protected XMLValidateTask.ValidatorErrorHandler` | `errorHandler`
    `protected boolean` | `failOnError`
    `protected java.io.File` | `file` file to be validated
    `protected java.util.Vector<FileSet>` | `filesets` sets of file to be validated
    `protected static java.lang.String` | `INIT_FAILED_MSG`
    `protected boolean` | `lenient`
    `static java.lang.String` | `MESSAGE_FILES_VALIDATED` Message for successful validation
    `protected java.lang.String` | `readerClassName`
    `protected boolean` | `warn`
    `protected org.xml.sax.XMLReader` | `xmlReader` the parser is viewed as a SAX2 XMLReader.

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XMLValidateTask()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConfiguredXMLCatalog(XMLCatalog catalog)` add an XMLCatalog as a nested element; optional.
    `void` | `addFileset(FileSet set)` specify a set of file to be checked
    `protected void` | `cleanup()` Cleans up resources.
    `XMLValidateTask.Attribute` | `createAttribute()` Add an attribute nested element.
    `Path` | `createClasspath()`
    `protected org.xml.sax.XMLReader` | `createDefaultReader()` Create a reader if the use of the class did not specify another one.
    `DTDLocation` | `createDTD()` Create a DTD location record; optional.
    `XMLValidateTask.Property` | `createProperty()` Creates a property.
    `protected org.xml.sax.XMLReader` | `createXmlReader()` create the XML reader.
    `protected boolean` | `doValidate(java.io.File afile)` parse the file
    `void` | `execute()` execute the task
    `protected org.xml.sax.EntityResolver` | `getEntityResolver()` accessor to the xmlCatalog used in the task
    `protected org.xml.sax.XMLReader` | `getXmlReader()` get the XML reader.
    `void` | `init()` Called by the project to let the task initialize properly.
    `protected void` | `initValidator()` init the parser : load the parser class, and set features if necessary It is only after this that the reader is valid
    `protected boolean` | `isSax1Parser()` test that returns true if we are using a SAX1 parser.
    `protected void` | `onSuccessfulValidation(int fileProcessed)` handler called on successful file validation.
    `void` | `setClassName(java.lang.String className)` Specify the class name of the SAX parser to be used.
    `void` | `setClasspath(Path classpath)` Specify the classpath to be searched to load the parser (optional)
    `void` | `setClasspathRef(Reference r)` Where to find the parser class; optional.
    `void` | `setFailOnError(boolean fail)` Specify how parser error are to be handled.
    `protected void` | `setFeature(java.lang.String feature, boolean value)` Set a feature on the parser.
    `void` | `setFile(java.io.File file)` specify the file to be checked; optional.
    `void` | `setLenient(boolean bool)` Specify whether the parser should be validating.
    `protected void` | `setProperty(java.lang.String name, java.lang.String value)` Sets a property.
    `void` | `setWarn(boolean bool)` Specify how parser error are to be handled.

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

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

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

- - ### Property Detail

    - #### create

          public XMLValidateTask.Property createProperty

      Creates a property.
      Since:
        ant 1.6.2

  - ### Field Detail

    - #### INIT_FAILED_MSG

          protected static final java.lang.String INIT_FAILED_MSG

      See Also:
        Constant Field Values

    - #### failOnError

          protected boolean failOnError

    - #### warn

          protected boolean warn

    - #### lenient

          protected boolean lenient

    - #### readerClassName

          protected java.lang.String readerClassName

    - #### file

          protected java.io.File file

      file to be validated

    - #### filesets

          protected java.util.Vector<FileSet> filesets

      sets of file to be validated

    - #### classpath

          protected Path classpath

    - #### xmlReader

          protected org.xml.sax.XMLReader xmlReader

      the parser is viewed as a SAX2 XMLReader. If a SAX1 parser is specified, it's wrapped in an adapter that make it behave as a XMLReader. a more 'standard' way of doing this would be to use the JAXP1.1 SAXParser interface.

    - #### errorHandler

          protected XMLValidateTask.ValidatorErrorHandler errorHandler

    - #### MESSAGE_FILES_VALIDATED

          public static final java.lang.String MESSAGE_FILES_VALIDATED

      Message for successful validation
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XMLValidateTask

          public XMLValidateTask()

  - ### Method Detail

    - #### setFailOnError

          public void setFailOnError(boolean fail)

      Specify how parser error are to be handled. Optional, default is `true`.

      If set to `true` (default), throw a buildException if the parser yields an error.

      Parameters:
        `fail` - if set to `false` do not fail on error

    - #### setWarn

          public void setWarn(boolean bool)

      Specify how parser error are to be handled.

      If set to `true` (default), log a warn message for each SAX warn event.

      Parameters:
        `bool` - if set to `false` do not send warnings

    - #### setLenient

          public void setLenient(boolean bool)

      Specify whether the parser should be validating. Default is `true`.

      If set to false, the validation will fail only if the parsed document is not well formed XML.

      this option is ignored if the specified class with `setClassName(String)` is not a SAX2 XMLReader.

      Parameters:
        `bool` - if set to `false` only fail on malformed XML

    - #### setClassName

          public void setClassName(java.lang.String className)

      Specify the class name of the SAX parser to be used. (optional)
      Parameters:
        `className` - should be an implementation of SAX2 `org.xml.sax.XMLReader` or SAX2 `org.xml.sax.Parser`.

        If className is an implementation of `org.xml.sax.Parser`, `setLenient(boolean)`, will be ignored.

        If not set, the default will be used.

      See Also:
        `XMLReader`, `Parser`

    - #### setClasspath

          public void setClasspath(Path classpath)

      Specify the classpath to be searched to load the parser (optional)
      Parameters:
        `classpath` - the classpath to load the parser

    - #### createClasspath

          public Path createClasspath()

      Returns:
        the classpath created
      See Also:
        `setClasspath(org.apache.tools.ant.types.Path)`

    - #### setClasspathRef

          public void setClasspathRef(Reference r)

      Where to find the parser class; optional.
      Parameters:
        `r` - reference to a classpath defined elsewhere
      See Also:
        `setClasspath(org.apache.tools.ant.types.Path)`

    - #### setFile

          public void setFile(java.io.File file)

      specify the file to be checked; optional.
      Parameters:
        `file` - the file to be checked

    - #### addConfiguredXMLCatalog

          public void addConfiguredXMLCatalog(XMLCatalog catalog)

      add an XMLCatalog as a nested element; optional.
      Parameters:
        `catalog` - XMLCatalog to use

    - #### addFileset

          public void addFileset(FileSet set)

      specify a set of file to be checked
      Parameters:
        `set` - the fileset to check

    - #### createAttribute

          public XMLValidateTask.Attribute createAttribute()

      Add an attribute nested element. This is used for setting arbitrary features of the SAX parser. Valid attributes include
      Returns:
        attribute created
      Since:
        ant1.6

    - #### createProperty

          public XMLValidateTask.Property createProperty()

      Creates a property.
      Since:
        ant 1.6.2

    - #### init

          public void init()
                    throws BuildException

      Called by the project to let the task initialize properly.
      Overrides:
        `init` in class `Task`
      Throws:
        `BuildException` - if something goes wrong with the build

    - #### createDTD

          public DTDLocation createDTD()

      Create a DTD location record; optional. This stores the location of a DTD. The DTD is identified by its public Id.
      Returns:
        created DTD location

    - #### getEntityResolver

          protected org.xml.sax.EntityResolver getEntityResolver()

      accessor to the xmlCatalog used in the task
      Returns:
        xmlCatalog reference

    - #### getXmlReader

          protected org.xml.sax.XMLReader getXmlReader()

      get the XML reader. Non-null only after `initValidator()`. If the reader is an instance of `ParserAdapter` then the parser is a SAX1 parser, and you cannot call `setFeature(String, boolean)` or `setProperty(String, String)` on it.
      Returns:
        the XML reader or null.

    - #### execute

          public void execute()
                       throws BuildException

      execute the task
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - if `failonerror` is true and an error happens

    - #### onSuccessfulValidation

          protected void onSuccessfulValidation(int fileProcessed)

      handler called on successful file validation.
      Parameters:
        `fileProcessed` - number of files processed.

    - #### initValidator

          protected void initValidator()

      init the parser : load the parser class, and set features if necessary It is only after this that the reader is valid
      Throws:
        `BuildException` - if something went wrong

    - #### isSax1Parser

          protected boolean isSax1Parser()

      test that returns true if we are using a SAX1 parser.
      Returns:
        true when a SAX1 parser is in use

    - #### createXmlReader

          protected org.xml.sax.XMLReader createXmlReader()

      create the XML reader. This is one by instantiating anything specified by `readerClassName`, falling back to a default reader if not. If the returned reader is an instance of `ParserAdapter` then we have created and wrapped a SAX1 parser.
      Returns:
        the new XMLReader.

    - #### cleanup

          protected void cleanup()

      Cleans up resources.
      Since:
        Ant 1.8.0

    - #### createDefaultReader

          protected org.xml.sax.XMLReader createDefaultReader()

      Create a reader if the use of the class did not specify another one. If a BuildException is thrown, the caller may revert to an alternate reader.
      Returns:
        a new reader.
      Throws:
        `BuildException` - if something went wrong

    - #### setFeature

          protected void setFeature(java.lang.String feature,
                                    boolean value)
                             throws BuildException

      Set a feature on the parser.
      Parameters:
        `feature` - the name of the feature to set
        `value` - the value of the feature
      Throws:
        `BuildException` - if the feature was not supported

    - #### setProperty

          protected void setProperty(java.lang.String name,
                                     java.lang.String value)
                              throws BuildException

      Sets a property.
      Parameters:
        `name` - a property name
        `value` - a property value.
      Throws:
        `BuildException` - if an error occurs.
        `BuildException` - if the property was not supported

    - #### doValidate

          protected boolean doValidate(java.io.File afile)

      parse the file
      Parameters:
        `afile` - the file to validate.
      Returns:
        true if the file validates.