org.apache.uima.analysis_engine

## Interface AnalysisEngineDescription

- All Superinterfaces:
    Cloneable, MetaDataObject, ResourceCreationSpecifier, ResourceSpecifier, Serializable, XMLizable
  All Known Subinterfaces:
    TaeDescription
  All Known Implementing Classes:
    AnalysisEngineDescription_impl, TaeDescription_impl

      public interface AnalysisEngineDescription
      extends ResourceCreationSpecifier

  An `AnalysisEngineDescription` contains all of the information needed to instantiate and use an `AnalysisEngine`.

  The `UIMAFramework.produceAnalysisEngine(ResourceSpecifier)` factory method is used to create an AnalysisEngine instance from a `AnalysisEngineDescription`. This insulates applications from knowledge of the particular AnalysisEngine implementation being used.

  The AnalysisEngine Description contains the following information:

  For a Primitive AnalysisEngine:

  - Name of main annotator class

  For an Aggregate AnalysisEngine:

  - A set of Resource Specifiers that specify the component AnalysisEngines that comprise the aggregate.
  - Optionally, a Resource Specifier for the FlowController component that determines routing of the CAS to the component AnalysisEngines.

  For All AnalysisEngines:

  - A set of Resource Specifiers that specify the external resources needed by this AnalysisEngine.
  - `Metadata` for this AnalysisEngine - this includes the capabilities of this AnalysisEngine, the TypeSystem used by this AnalysisEngine, and other parameters.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `doFullValidation()` Does full validation of this Analysis Engine Description.
    `void` | `doFullValidation(ResourceManager aResourceManager)` Does full validation of this Analysis Engine Description.
    `Map<String,ResourceSpecifier>` | `getAllComponentSpecifiers(ResourceManager aResourceManager)` For an aggregate AnalysisEngine only, gets the ResourceSpecifiers of all components in this aggregate.
    `AnalysisEngineMetaData` | `getAnalysisEngineMetaData()` Retrieves the metadata that describes the AnalysisEngine.
    `String` | `getAnnotatorImplementationName()` For a primitive AnalysisEngine only, retrieves the name of the annotator implementation.
    `ResourceSpecifier` | `getComponentSpecifier(String key)` Gets the ResourceSpecifier of one a component of this aggregate, based on its key.
    `Map<String,ResourceSpecifier>` | `getDelegateAnalysisEngineSpecifiers()` For an aggregate AnalysisEngine only, retrieves a collection of `ResourceSpecifier`s that indicate which delegate AnalysisEngines comprise the aggregate.
    `Map<String,ResourceSpecifier>` | `getDelegateAnalysisEngineSpecifiers(ResourceManager aResourceManager)` For an aggregate AnalysisEngine only, retrieves a collection of `ResourceSpecifier`s that indicate which delegate AnalysisEngines comprise the aggregate.
    `Map<String,MetaDataObject>` | `getDelegateAnalysisEngineSpecifiersWithImports()` Retrieves a Map whose keys are string identifiers and whose values are the either `Import` or `ResourceSpecifier` objects.
    `FlowControllerDeclaration` | `getFlowControllerDeclaration()` For an aggregate AnalysisEngine only, gets the declaration of which FlowController should be used by the AnalysisEngine.
    `String` | `getFrameworkImplementation()` Gets the name of the framework implementation within which the AnalysisEngine executes.
    `SofaMapping[]` | `getSofaMappings()`
    `boolean` | `isPrimitive()` Retrieves whether the AnalysisEngine is primitive (consisting of one annotator), as opposed to aggregate (containing multiple delegate AnalysisEngines).
    `void` | `resolveImports(Collection<String> aAlreadyImportedDelegateAeUrls, ResourceManager aResourceManager)` Resolves all import declarations in this AnalysisEngineDescription.
    `void` | `resolveImports(ResourceManager aResourceManager)` Resolves all import declarations in this AnalysisEngineDescription.
    `void` | `setAnnotatorImplementationName(String aImplementationName)` For a primitive AnalysisEngine only, sets the name of the annotator implementation.
    `void` | `setFlowControllerDeclaration(FlowControllerDeclaration aFlowControllerDeclaration)` For an aggregate AnalysisEngine only, sets the declaration of which FlowController should be used by the AnalysisEngine.
    `void` | `setFrameworkImplementation(String aFrameworkImplementation)` Sets the name of the framework implementation within which the AnalysisEngine executes.
    `void` | `setPrimitive(boolean aPrimitive)` Sets whether the AnalysisEngine is primitive (consisting of one annotator), as opposed to aggregate (containing multiple delegate AnalysisEngines).
    `void` | `setSofaMappings(SofaMapping[] aSofaMappings)`
    `void` | `toXML(ContentHandler aContentHandler, boolean aWriteDefaultNamespaceAttribute, boolean aPreserveDelegateAnalysisEngineImports)` Writes this object's XML representation by making calls on a SAX `ContentHandler`.
    `void` | `toXML(OutputStream aOutputStream, boolean aPreserveDelegateAnalysisEngineImports)` Writes this object's XML representation as a string in UTF-8 encoding.
    `void` | `toXML(Writer aWriter, boolean aPreserveDelegateAnalysisEngineImports)` Writes this object's XML representation as a string.

    - ### Methods inherited from interface org.apache.uima.resource.ResourceCreationSpecifier

      `getExternalResourceDependencies, getExternalResourceDependency, getImplementationName, getMetaData, getResourceManagerConfiguration, setExternalResourceDependencies, setImplementationName, setMetaData, setResourceManagerConfiguration, validate, validate`

    - ### Methods inherited from interface org.apache.uima.resource.metadata.MetaDataObject

      `clone, equals, getAttributeValue, getSourceUrl, getSourceUrlString, isModifiable, listAttributes, setAttributeValue, setSourceUrl`

    - ### Methods inherited from interface org.apache.uima.util.XMLizable

      `buildFromXMLElement, buildFromXMLElement, toXML, toXML, toXML, toXML`

- - ### Method Detail

    - #### getFrameworkImplementation

          String getFrameworkImplementation()

      Gets the name of the framework implementation within which the AnalysisEngine executes. The framework name for this implementation is given by `Constants.JAVA_FRAMEWORK_NAME`.
      Specified by:
        `getFrameworkImplementation` in interface `ResourceCreationSpecifier`
      Returns:
        the framework implementation name

    - #### setFrameworkImplementation

          void setFrameworkImplementation(String aFrameworkImplementation)

      Sets the name of the framework implementation within which the AnalysisEngine executes. The framework name for this implementation is given by `Constants.JAVA_FRAMEWORK_NAME`.
      Specified by:
        `setFrameworkImplementation` in interface `ResourceCreationSpecifier`
      Parameters:
        `aFrameworkImplementation` - the framework implementation name

    - #### isPrimitive

          boolean isPrimitive()

      Retrieves whether the AnalysisEngine is primitive (consisting of one annotator), as opposed to aggregate (containing multiple delegate AnalysisEngines).

      Some of the methods on this class apply only to one type of AnalysisEngine:
      `getAnnotatorImplementationName()` - primitive AnalysisEngine only
      `getDelegateAnalysisEngineSpecifiers()` - aggregate AnalysisEngine only
      `getFlowControllerDeclaration()` - aggregate AnalysisEngine only

      Returns:
        true if and only if the AnalysisEngine is primitive

    - #### setPrimitive

          void setPrimitive(boolean aPrimitive)

      Sets whether the AnalysisEngine is primitive (consisting of one annotator), as opposed to aggregate (containing multiple delegate AnalysisEngines).
      Parameters:
        `aPrimitive` - true if and only if the AnalysisEngine is primitive

    - #### getAnnotatorImplementationName

          String getAnnotatorImplementationName()

      For a primitive AnalysisEngine only, retrieves the name of the annotator implementation. For Java annotators, this will be a fully qualified Java class name.
      Returns:
        the implementation name of the annotator. If the AnalysisEngine is aggregate, always returns `null`.

    - #### setAnnotatorImplementationName

          void setAnnotatorImplementationName(String aImplementationName)

      For a primitive AnalysisEngine only, sets the name of the annotator implementation. For Java annotators, this must be a fully qualified Java class name.
      Parameters:
        `aImplementationName` - the implementation name of the annotator.

    - #### getDelegateAnalysisEngineSpecifiers

          Map<String,ResourceSpecifier> getDelegateAnalysisEngineSpecifiers()
                                                                     throws InvalidXMLException

      For an aggregate AnalysisEngine only, retrieves a collection of `ResourceSpecifier`s that indicate which delegate AnalysisEngines comprise the aggregate. Each `ResourceSpecifier` can either:
      1. completely describe how to build a AnalysisEngine instance
      2. describe how to locate a distributed AnalysisEngine service, for example a specific endpoint or a JNDI name

      This method returns an unmodifiable Map whose keys are string identifiers and whose values are the `ResourceSpecifier` objects. The string identifiers in this Map are to refer to the delegate AnalysisEngines from elsewhere in this `AnalysisEngineDescription`. (For example in the `FlowConstraints` description.)

      Note that the Map returned by this method will never contain `Import` objects -- they will always be resolved first. If you want to get access to the original Import objects, use `getDelegateAnalysisEngineSpecifiersWithImports()`. Also use that method if you want to be able to make changes to the Map.

      Returns:
        an unmodifiable Map with `String` keys and `ResourceSpecifier` values.
      Throws:
        `InvalidXMLException` - if import resolution failed

    - #### getDelegateAnalysisEngineSpecifiers

          Map<String,ResourceSpecifier> getDelegateAnalysisEngineSpecifiers(ResourceManager aResourceManager)
                                                                     throws InvalidXMLException

      For an aggregate AnalysisEngine only, retrieves a collection of `ResourceSpecifier`s that indicate which delegate AnalysisEngines comprise the aggregate. Each `ResourceSpecifier` can either:
      1. completely describe how to build a AnalysisEngine instance
      2. describe how to locate a distributed AnalysisEngine service, for example a specific endpoint or a JNDI name

      This method returns an unmodifiable Map whose keys are string identifiers and whose values are the `ResourceSpecifier` objects. The string identifiers in this Map are to refer to the delegate AnalysisEngines from elsewhere in this `AnalysisEngineDescription`. (For example in the `FlowConstraints` description.)

      Note that the Map returned by this method will never contain `Import` objects -- they will always be resolved first. If you want to get access to the original Import objects, use `getDelegateAnalysisEngineSpecifiersWithImports()`. Also use that method if you want to be able to make changes to the Map.

      Parameters:
        `aResourceManager` - the ResourceManager to use to get the datapath needed to resolve imports
      Returns:
        an unmodifiable Map with `String` keys and `ResourceSpecifier` values.
      Throws:
        `InvalidXMLException` - if import resolution failed

    - #### getDelegateAnalysisEngineSpecifiersWithImports

          Map<String,MetaDataObject> getDelegateAnalysisEngineSpecifiersWithImports()

      Retrieves a Map whose keys are string identifiers and whose values are the either `Import` or `ResourceSpecifier` objects. These indicate the delegate AnalysisEngines that comprise the aggregate.

      This is a direct representation of what is in the XML syntax for the descriptor. That is, if the XML had an <import> element, the Map will contain an `Import` object. If you do not want to deal with imports, use the `getDelegateAnalysisEngineSpecifiers()` method instead.

      Returns:
        a Map with `String` keys and `ResourceSpecifier` or `Import` objects as values. This Map may be modified to add or remove imports or specifiers.

    - #### getFlowControllerDeclaration

          FlowControllerDeclaration getFlowControllerDeclaration()

      For an aggregate AnalysisEngine only, gets the declaration of which FlowController should be used by the AnalysisEngine.
      Returns:
        an object containing either an import of a ResourceSpecifier or a ResourceSpecifier itself. This specifier will be used to create the FlowController.

    - #### setFlowControllerDeclaration

          void setFlowControllerDeclaration(FlowControllerDeclaration aFlowControllerDeclaration)

      For an aggregate AnalysisEngine only, sets the declaration of which FlowController should be used by the AnalysisEngine.
      Parameters:
        `aFlowControllerDeclaration` - an object containing either an import of a ResourceSpecifier or a ResourceSpecifier itself. This specifier will be used to create the FlowController.

    - #### getAllComponentSpecifiers

          Map<String,ResourceSpecifier> getAllComponentSpecifiers(ResourceManager aResourceManager)
                                                           throws InvalidXMLException

      For an aggregate AnalysisEngine only, gets the ResourceSpecifiers of all components in this aggregate. This includes the FlowController as well as all of the component AnalysisEngines.

      This method returns an unmodifiable Map whose keys are string identifiers and whose values are the `ResourceSpecifier` objects. The string identifiers in this Map are to refer to the components from elsewhere in this aggregate descriptor, for example in configuration parameter overrides and resource bindings.

      Note that the Map returned by this method will never contain `Import` objects -- they will always be resolved first. If you want to get access to the original Import objects, use `getDelegateAnalysisEngineSpecifiersWithImports()` and `getFlowControllerDeclaration()`. Also use those methods if you want to make changes to be able to make changes to the Map.

      Parameters:
        `aResourceManager` - the ResourceManager from which to get the datapath needed to resolve imports. Pass null to use the default ResourceManager.
      Returns:
        an unmodifiable Map with `String` keys and `ResourceSpecifier` values.
      Throws:
        `InvalidXMLException` - if import resolution failed

    - #### getAnalysisEngineMetaData

          AnalysisEngineMetaData getAnalysisEngineMetaData()

      Retrieves the metadata that describes the AnalysisEngine. This includes the AnalysisEngine's capabilties, the TypeSystem that is uses, the specified Flow information for an aggregate AnalysisEngine, and various informational attributes such as name, description, version, vendor, and copyright.
      Returns:
        the `AnalysisEngineMetaData` object containing the AnalysisEngine's metadata. This object can be modified.

    - #### getSofaMappings

          SofaMapping[] getSofaMappings()

    - #### setSofaMappings

          void setSofaMappings(SofaMapping[] aSofaMappings)

    - #### getComponentSpecifier

          ResourceSpecifier getComponentSpecifier(String key)
                                           throws ResourceInitializationException

      Gets the ResourceSpecifier of one a component of this aggregate, based on its key. This may be the specifier of a component (i.e. delegate) AnalysisEngine, or it may be the specifier of the FlowController.
      Parameters:
        `key` - the key of the component specifier to get
      Returns:
        the specifier for the component, null if there is no component with the given key
      Throws:
        `ResourceInitializationException` - if there's a problem resolving imports

    - #### doFullValidation

          void doFullValidation()
                         throws ResourceInitializationException

      Does full validation of this Analysis Engine Description. This essentially performs all operations necessary to instantiate an Analysis Engine from this description, except that it does not actually instantiate the Annotator classes (although it does try to load these classes). This method will also attempt to create a CAS based on the descriptor, in order to do full type system verification. If any operations fail, an exception will be thrown.
      Specified by:
        `doFullValidation` in interface `ResourceCreationSpecifier`
      Throws:
        `ResourceInitializationException` - if validation failed

    - #### doFullValidation

          void doFullValidation(ResourceManager aResourceManager)
                         throws ResourceInitializationException

      Does full validation of this Analysis Engine Description. This essentially performs all operations necessary to instantiate an Analysis Engine from this description, except that it does not actually instantiate the Annotator classes (although it does try to load these classes). This method will also attempt to create a CAS based on the descriptor, in order to do full type system verification. If any operations fail, an exception will be thrown.
      Specified by:
        `doFullValidation` in interface `ResourceCreationSpecifier`
      Parameters:
        `aResourceManager` - a ResourceManager instance to use to load annotator classes, external resource classes, and resolve imports by name.
      Throws:
        `ResourceInitializationException` - if validation failed

    - #### resolveImports

          void resolveImports(ResourceManager aResourceManager)
                       throws InvalidXMLException

      Resolves all import declarations in this AnalysisEngineDescription. For an aggregate, this is recursive, also resolving all imports in each delegate AnalysisEngine. Users do not typically need to call this method; it is called automatically when `UIMAFramework.produceAnalysisEngine(ResourceSpecifier)` is called.
      Parameters:
        `aResourceManager` - the Resource Manager used to locate imports by name. For example, the path in which to locate these imported descriptors can be set via the `ResourceManager.setDataPath(String)` method.
      Throws:
        `InvalidXMLException` - if an import target does not exist or is invalid

    - #### resolveImports

          void resolveImports(Collection<String> aAlreadyImportedDelegateAeUrls,
                              ResourceManager aResourceManager)
                       throws InvalidXMLException

      Resolves all import declarations in this AnalysisEngineDescription. For an aggregate, this is recursive, also resolving all imports in each delegate AnalysisEngine. Users do not typically need to call this method; it is called automatically when `UIMAFramework.produceAnalysisEngine(ResourceSpecifier)` is called.

      This version is used internally to resolve nested imports.

      Parameters:
        `aAlreadyImportedDelegateAeUrls` - URLs of already imported AE descriptors, so we don't import them again.
        `aResourceManager` - the Resource Manager used to locate imports by name. For example, the path in which to locate these imported descriptors can be set via the `ResourceManager.setDataPath(String)` method.
      Throws:
        `InvalidXMLException` - if an import target does not exist or is invalid

    - #### toXML

          void toXML(Writer aWriter,
                     boolean aPreserveDelegateAnalysisEngineImports)
              throws SAXException,
                     IOException

      Writes this object's XML representation as a string. Note that if you want to write the XML to a file, it is highly recommended that you use `XMLizable.toXML(OutputStream)` instead, as it ensures that output is written in UTF-8 encoding, which is the default encoding that should be used for XML files.
      Parameters:
        `aWriter` - a Writer to which the XML string will be written
        `aPreserveDelegateAnalysisEngineImports` - if true, XML serialization will always preserve <import> elements used to import delegate analysis engine specifiers into an aggregate. If false, the default import serialization behavior applies, which is to write <import> elements only in the case where they have not previously been resolved.
      Throws:
        `IOException` - if an I/O failure occurs
        `SAXException` - if a SAX exception occurs

    - #### toXML

          void toXML(OutputStream aOutputStream,
                     boolean aPreserveDelegateAnalysisEngineImports)
              throws SAXException,
                     IOException

      Writes this object's XML representation as a string in UTF-8 encoding.
      Parameters:
        `aOutputStream` - an OutputStream to which the XML string will be written, in UTF-8 encoding.
        `aPreserveDelegateAnalysisEngineImports` - if true, XML serialization will always preserve <import> elements used to import delegate analysis engine specifiers into an aggregate. If false, the default import serialization behavior applies, which is to write <import> elements only in the case where they have not previously been resolved.
      Throws:
        `IOException` - if an I/O failure occurs
        `SAXException` - if a SAX exception occurs

    - #### toXML

          void toXML(ContentHandler aContentHandler,
                     boolean aWriteDefaultNamespaceAttribute,
                     boolean aPreserveDelegateAnalysisEngineImports)
              throws SAXException

      Writes this object's XML representation by making calls on a SAX `ContentHandler`.
      Parameters:
        `aContentHandler` - the content handler to which this object will write events that describe its XML representation.
        `aWriteDefaultNamespaceAttribute` - whether the namespace of this element should be written as the default namespace. This should be done only for the root element, and it defaults to false.
        `aPreserveDelegateAnalysisEngineImports` - if true, XML serialization will always preserve <import> elements used to import delegate analysis engine specifiers into an aggregate. If false, the default import serialization behavior applies, which is to write <import> elements only in the case where they have not previously been resolved.
      Throws:
        `SAXException` - if a SAX exception occurs

Copyright © 2006–2022 The Apache Software Foundation. All rights reserved.