Package org.apache.uima.util

Interface XMLParser

All Known Implementing Classes:
XMLParser_impl
public interface XMLParser
A UIMA XMLParser parses XML documents and generates UIMA components represented by the XML.

An application obtains a reference to the XMLParser by calling the UIMAFramework.getXMLParser() method. The application then uses the XMLParser by passing an InputStream to one of its parse methods - for example parseAnalysisEngineDescription(XMLInputSource) for parsing an AnalysisEngineDescription from its XML representation.

XML schema validation is off by default; it can be turned on by calling the method enableSchemaValidation(boolean).

UIMA developers who provide new types of XMLizable components must configure the XML parser by using the addMapping(String,String) method to specify mappings between XML Element names and the class names of the objects to be built from elements with those names. All objects to be built by the XML parser must implement XMLizable and provide an implementation of XMLizable.buildFromXMLElement(Element, XMLParser).

Note that we are considering replacing this ad-hoc XML data binding interface with the java standard extension JAXB. See http://java.sun.com/xml/jaxb for details on JAXB.

  • Field Details

    • RESOURCE_SPECIFIER_NAMESPACE

      static final String RESOURCE_SPECIFIER_NAMESPACE
      XML namespace for ResourceSpecifiers. XML ResourceSpecifier documents must use this namespace or they will be considered invalid by the schema validator.
      See Also:

    • RESOURCE_SPECIFIER_SCHEMA_NAME

      static final String RESOURCE_SPECIFIER_SCHEMA_NAME
      Name of schema for ResourceSpecifiers. This file will be looked up in the classpath.
      See Also:

  • Method Details

    • enableSchemaValidation

      void enableSchemaValidation(boolean aEnable)
      Enables or disables XML schema validation.
      Parameters:
      aEnable - true to enable validation, false to disable validation

    • parse

      XMLizable parse(XMLInputSource aInput, String aNamespaceForSchema, URL aSchemaUrl) throws InvalidXMLException
      Parses an XML input stream and produces an object. elements.
      Parameters:
      aInput - the input source from which to read the XML document
      aNamespaceForSchema - XML namespace for elements to be validated against XML schema. If null, no schema will be used (unless one is declared in the document itself). This parameter is ignored if schema validation has not been enabled via enableSchemaValidation(boolean).
      aSchemaUrl - URL to XML schema that will be used to validate the XML document. If null, no schema will be used (unless one is declared in the document itself). This parameter is ignored if schema validation has not been enabled via enableSchemaValidation(boolean).
      Returns:
      an XMLizable object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid object

    • parse

      XMLizable parse(XMLInputSource aInput, String aNamespaceForSchema, URL aSchemaUrl, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses an XML input stream and produces an object.
      Parameters:
      aInput - the input source from which to read the XML document
      aNamespaceForSchema - XML namespace for elements to be validated against XML schema. If null, no schema will be used (unless one is declared in the document itself). This parameter is ignored if schema validation has not been enabled via enableSchemaValidation(boolean).
      aSchemaUrl - URL to XML schema that will be used to validate the XML document. If null, no schema will be used (unless one is declared in the document itself). This parameter is ignored if schema validation has not been enabled via enableSchemaValidation(boolean).
      aOptions - option settings
      Returns:
      an XMLizable object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid object

    • parse

      XMLizable parse(XMLInputSource aInput) throws InvalidXMLException
      Parses an XML input stream and produces an object. XIncludes will be expanded but no schema validation will be done.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      an XMLizable object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid object

    • parse

      XMLizable parse(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses an XML input stream and produces an object. No schema validation will be done.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      an XMLizable object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid object

    • parseResourceSpecifier

      ResourceSpecifier parseResourceSpecifier(XMLInputSource aInput) throws InvalidXMLException
      Parses a ResourceSpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a ResourceSpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResourceSpecifier

    • parseResourceSpecifier

      ResourceSpecifier parseResourceSpecifier(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a ResourceSpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a ResourceSpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResourceSpecifier

    • parseResourceMetaData

      ResourceMetaData parseResourceMetaData(XMLInputSource aInput) throws InvalidXMLException
      Parses a ResourceMetaData object from an XML input stream. XML schema validation will be done against the RESOURCE_SPECIFIER_SCHEMA_NAME if it can be found in the classpath.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a ResourceMetaData object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResourceSpecifier

    • parseResourceMetaData

      ResourceMetaData parseResourceMetaData(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a ResourceMetaData object from an XML input stream. XML schema validation will be done against the RESOURCE_SPECIFIER_SCHEMA_NAME if it can be found in the classpath.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a ResourceMetaData object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResourceSpecifier

    • parseURISpecifier

      URISpecifier parseURISpecifier(XMLInputSource aInput) throws InvalidXMLException
      Parses a URISpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a URISpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid URISpecifier

    • parseURISpecifier

      URISpecifier parseURISpecifier(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a URISpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a URISpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid URISpecifier

    • parseAnalysisEngineDescription

      AnalysisEngineDescription parseAnalysisEngineDescription(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses an AnalysisEngineDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      an AnalysisEngineDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid AnalysisEngineDescription

    • parseAnalysisEngineDescription

      AnalysisEngineDescription parseAnalysisEngineDescription(XMLInputSource aInput) throws InvalidXMLException
      Parses an AnalysisEngineDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      an AnalysisEngineDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid AnalysisEngineDescription

    • parseTaeDescription

      @Deprecated TaeDescription parseTaeDescription(XMLInputSource aInput) throws InvalidXMLException
      Deprecated.
      As of v2.0, parseAnalysisEngineDescription(XMLInputSource) should be used instead.
      Parses a TaeDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a TaeDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid TaeDescription

    • parseTaeDescription

      @Deprecated TaeDescription parseTaeDescription(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Deprecated.
      As of v2.0, parseAnalysisEngineDescription(XMLInputSource,ParsingOptions) should be used instead.
      Parses a TaeDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a TaeDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid TaeDescription

    • parseCasConsumerDescription

      CasConsumerDescription parseCasConsumerDescription(XMLInputSource aInput) throws InvalidXMLException
      Parses a CasConsumerDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a CasConsumerDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CasConsumerDescription

    • parseCasConsumerDescription

      CasConsumerDescription parseCasConsumerDescription(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a CasConsumerDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a CasConsumerDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CasConsumerDescription

    • parseCasInitializerDescription

      CasInitializerDescription parseCasInitializerDescription(XMLInputSource aInput) throws InvalidXMLException
      Parses a CasInitializerDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a CasInitializerDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CasInitializerDescription

    • parseCasInitializerDescription

      CasInitializerDescription parseCasInitializerDescription(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a CasInitializerDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a CasInitializerDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CasInitializerDescription

    • parseCollectionReaderDescription

      CollectionReaderDescription parseCollectionReaderDescription(XMLInputSource aInput) throws InvalidXMLException
      Parses a CollectionReaderDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a CollectionReaderDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CollectionReaderDescription

    • parseCollectionReaderDescription

      CollectionReaderDescription parseCollectionReaderDescription(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a CollectionReaderDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a CollectionReaderDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CollectionReaderDescription

    • parseCpeDescription

      CpeDescription parseCpeDescription(XMLInputSource aInput) throws InvalidXMLException
      Parses a CpeDescription from an XML input stream.

      NOTE: the option settings XMLParser.ParsingOptions are not currently available for parsing CpeDescriptions, because they use a different parsing mechanism than the other specifier types.

      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a cpeDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid IndexingSpecification

    • parseResultSpecification

      ResultSpecification parseResultSpecification(XMLInputSource aInput) throws InvalidXMLException
      Parses a ResultSpecification from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a ResultSpecification object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResultSpecification

    • parseResultSpecification

      ResultSpecification parseResultSpecification(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a ResultSpecification from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a ResultSpecification object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResultSpecification

    • parseTypeSystemDescription

      TypeSystemDescription parseTypeSystemDescription(XMLInputSource aInput) throws InvalidXMLException
      Parses a TypeSystemDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a TypeSystemDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid TypeSystemDescription

    • parseTypeSystemDescription

      TypeSystemDescription parseTypeSystemDescription(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a TypeSystemDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a TypeSystemDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid TypeSystemDescription

    • parseTypePriorities

      TypePriorities parseTypePriorities(XMLInputSource aInput) throws InvalidXMLException
      Parses a TypePriorities declaration from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a TypePriorities object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid TypePriorities

    • parseTypePriorities

      TypePriorities parseTypePriorities(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a TypePriorities declaration from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a TypePriorities object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid TypePriorities

    • parseFsIndexCollection

      FsIndexCollection parseFsIndexCollection(XMLInputSource aInput) throws InvalidXMLException
      Parses a FsIndexCollection from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a FsIndexCollection object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid FsIndexCollection

    • parseFsIndexCollection

      FsIndexCollection parseFsIndexCollection(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a FsIndexCollection from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a FsIndexCollection object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid FsIndexCollection

    • parseResourceManagerConfiguration

      ResourceManagerConfiguration parseResourceManagerConfiguration(XMLInputSource aInput) throws InvalidXMLException
      Parses a ResourceManagerConfiguration from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a ResourceManagerConfiguration object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResourceManagerConfiguration

    • parseResourceManagerConfiguration

      ResourceManagerConfiguration parseResourceManagerConfiguration(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a ResourceManagerConfiguration from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a ResourceManagerConfiguration object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid ResourceManagerConfiguration

    • parseFlowControllerDescription

      FlowControllerDescription parseFlowControllerDescription(XMLInputSource aInput) throws InvalidXMLException
      Parses a FlowControllerDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a FlowControllerDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid FlowControllerDescription

    • parseFlowControllerDescription

      FlowControllerDescription parseFlowControllerDescription(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a FlowControllerDescription from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a FlowControllerDescription object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid FlowControllerDescription

    • parseCustomResourceSpecifier

      CustomResourceSpecifier parseCustomResourceSpecifier(XMLInputSource aInput) throws InvalidXMLException
      Parses a CustomResourceSpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a CustomResourceSpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CustomResourceSpecifier

    • parseCustomResourceSpecifier

      CustomResourceSpecifier parseCustomResourceSpecifier(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a CustomResourceSpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a CustomResourceSpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid CustomResourceSpecifier

    • parsePearSpecifier

      PearSpecifier parsePearSpecifier(XMLInputSource aInput) throws InvalidXMLException
      Parses a PearSpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      a PearSpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid PearSpecifier

    • parsePearSpecifier

      PearSpecifier parsePearSpecifier(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses a PearSpecifier from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      a PearSpecifier object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid PearSpecifier

    • parseIndexBuildSpecification

      IndexBuildSpecification parseIndexBuildSpecification(XMLInputSource aInput) throws InvalidXMLException
      Parses an IndexBuildSpecification from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      Returns:
      an IndexBuildSpecification object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid IndexBuildSpecification

    • parseIndexBuildSpecification

      IndexBuildSpecification parseIndexBuildSpecification(XMLInputSource aInput, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Parses an IndexBuildSpecification from an XML input stream.
      Parameters:
      aInput - the input source from which to read the XML document
      aOptions - option settings
      Returns:
      an IndexBuildSpecification object constructed from the XML document
      Throws:
      InvalidXMLException - if the input XML is not valid or does not specify a valid IndexBuildSpecification

    • buildObject

      XMLizable buildObject(Element aElement) throws InvalidXMLException
      Builds an object from its XML DOM representation. This method is not typically called by applications. It may be called from within a XMLizable.buildFromXMLElement(Element, XMLParser) method to construct sub-objects.
      Parameters:
      aElement - a DOM Element
      Returns:
      an XMLizable object constructed from the DOM element
      Throws:
      InvalidXMLException - if the XML element does not specify a valid object

    • buildObject

      XMLizable buildObject(Element aElement, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Builds an object from its XML DOM representation. This method is not typically called by applications. It may be called from within a XMLizable.buildFromXMLElement(Element, XMLParser) method to construct sub-objects.
      Parameters:
      aElement - a DOM Element
      aOptions - option settings
      Returns:
      an XMLizable object constructed from the DOM element
      Throws:
      InvalidXMLException - if the XML element does not specify a valid object

    • buildObjectOrPrimitive

      Object buildObjectOrPrimitive(Element aElement, XMLParser.ParsingOptions aOptions) throws InvalidXMLException
      Builds an object from its XML DOM representation. This method is not typically called by applications. It may be called from within a XMLizable.buildFromXMLElement(Element, XMLParser) method to construct sub-objects.

      This method is similar to buildObject(Element, XMLParser.ParsingOptions) but can also parse primitive-typed objects wrapped as XML elements, such as <integer>42</integer.

      Parameters:
      aElement - a DOM Element
      aOptions - option settings
      Returns:
      an object constructed from the DOM element. This can be either an instance of XMLizable, String, or one of the primitive type wrapper objects (e.g. Integer, Float, Boolean).
      Throws:
      InvalidXMLException - if the XML element does not specify a valid object

    • newSaxDeserializer

      SaxDeserializer newSaxDeserializer()
      Creates a new SaxDeserializer object, which implements the SAX ContentHandler interface and can be used to deserialize an XMLizable object from the events sent from a SAX parser. This can be used if the application already has a SAX parser that generates these events. In most cases, it is easier to use one of the parse methods on this interface.

      The SAX deserializer returned my this method will expand XIncludes but will not do schema validation.

      Returns:
      an object that implements ContentHandler and can be used to deserialize an XMLizable object from SAX events.

    • newSaxDeserializer

      SaxDeserializer newSaxDeserializer(XMLParser.ParsingOptions aOptions)
      Creates a new SaxDeserializer.
      Parameters:
      aOptions - option settings
      Returns:
      an object that implements ContentHandler and can be used to deserialize an XMLizable object from SAX events.
      See Also:

    • addMapping

      void addMapping(String aElementName, String aClassName) throws ClassNotFoundException
      Configures this XMLParser by registering a mapping between the name of an XML element and the Class of object to be built from elements with that name.
      Parameters:
      aElementName - the name of an XML element
      aClassName - the name of a Class of object to be built. This class must implement XMLizable and have a zero-argument constructor.
      Throws:
      ClassNotFoundException - if the class named by aClassName could not be found