Package org.apache.uima

# Interface UimaContext

All Known Subinterfaces:
  `FlowControllerContext`, `UimaContextAdmin`

All Known Implementing Classes:
  `ChildUimaContext_impl`, `FlowControllerContext_impl`, `RootUimaContext_impl`, `UimaContext_ImplBase`

public interface UimaContext
Provides access to external resources (other than the CAS). The `UimaContext` provides UIMA resources (e.g. Annotators, Collection Readers, CAS Consumers, CAS Initializers) with all access to external resources (other than the `CAS`). Examples include:

- Configuration Parameters
- Logging & Instrumentation Facilities
- Access to External Analysis Resources, such as dictionary files

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String[]`
  `getConfigParameterNames()`
  Gets the names of all configuration parameters that are not declared in a group.
  `String[]`
  `getConfigParameterNames(String aGroup)`
  Gets the names of all configuration parameters in the specified group.
  `Object`
  `getConfigParameterValue(String aParamName)`
  Retrieves the value for a configuration parameter that is not defined in any group or is defined in the default group.
  `Object`
  `getConfigParameterValue(String aGroupName, String aParamName)`
  Retrieves the value for a configuration parameter in a particular group.
  `String[]`
  `getConfigurationGroupNames()`
  Gets the names of all configuration parameter groups.
  `String`
  `getDataPath()`
  Deprecated.
  Use `getDataPathElements()` instead.
  `List<String>`
  `getDataPathElements()`
  Gets the data path elements used to resolve relative paths.
  `<T extends AbstractCas>
  T`
  `getEmptyCas(Class<T> aCasInterface)`
  Get an empty CAS.
  `Settings`
  `getExternalOverrides()`
  Gets the `Settings` used for external parameter overrides
  `InstrumentationFacility`
  `getInstrumentationFacility()`
  Gets the `InstrumentationFacility` that a component can use to record information about its performance.
  `Logger`
  `getLogger()`
  Gets the `Logger` to which log output will be sent.
  `InputStream`
  `getResourceAsStream(String aKey)`
  Retrieves an InputStream for reading from the named resource.
  `InputStream`
  `getResourceAsStream(String aKey, String[] aParams)`
  Retrieves an InputStream for reading from the named resource.
  `String`
  `getResourceFilePath(String aKey)`
  Retrieves the absolute file path to the named resource.
  `String`
  `getResourceFilePath(String aKey, String[] aParams)`
  Retrieves the absolute file path to the named resource.
  `Object`
  `getResourceObject(String aKey)`
  Retrieves the named resource object.
  `Object`
  `getResourceObject(String aKey, String[] aParams)`
  Retrieves the named resource object.
  `URI`
  `getResourceURI(String aKey)`
  Retrieves the URI to the named resource.
  `URI`
  `getResourceURI(String aKey, String[] aParams)`
  Retrieves the URI to the named resource.
  `URL`
  `getResourceURL(String aKey)`
  Retrieves the URL to the named resource.
  `URL`
  `getResourceURL(String aKey, String[] aParams)`
  Retrieves the URL to the named resource.
  `Session`
  `getSession()`
  Returns the Session object, which can be used to store data that pertains to a particular client session.
  `String[]`
  `getSharedSettingArray(String name)`
  Get the array of values for a shared configuration parameter from the external override settings.
  `String[]`
  `getSharedSettingNames()`
  Get the names of all the external override settings available.
  `String`
  `getSharedSettingValue(String name)`
  Get the value of a shared configuration parameter from the external override settings.
  `SofaID[]`
  `getSofaMappings()`
  Deprecated.
  As of v2.0, annotators no longer need to explicitly call this method.
  `String`
  `mapSofaIDToComponentSofaName(String aSofaID)`
  Retrieve the sofa name as known to the component given an absolute Sofa ID.
  `SofaID`
  `mapToSofaID(String aSofaName)`
  Deprecated.
  As of v2.0, annotators no longer need to explicitly call this method.

- ## Method Details

  - ### getConfigParameterValue

    Object getConfigParameterValue(String aParamName)
    Retrieves the value for a configuration parameter that is not defined in any group or is defined in the default group.

    This method returns `null` if the parameter is optional and has not been assigned a value. (For mandatory parameters, an exception is thrown during initialization if no value has been assigned.) This method also returns `null` if there is no declared configuration parameter with the specified name.

    Parameters:
      `aParamName` - the name of the parameter to look up
    Returns:
      the value of the parameter with the given name. The caller is expected to know the data type of the parameter. Returns `null` if the parameter does not exist or has not been assigned a value.

  - ### getConfigParameterValue

    Object getConfigParameterValue(String aGroupName, String aParamName)
    Retrieves the value for a configuration parameter in a particular group. If that group contains no value for the specified parameter, the fallback strategy specified by the Analysis Engine's `ConfigurationParameterDeclarations.getSearchStrategy()` property will be used. The search strategy can be specified in the descriptor.

    This method returns `null` if the parameter is optional and has not been assigned a value. (For mandatory parameters, an exception is thrown during initialization if no value has been assigned.) This method also returns `null` if there is no declared configuration parameter with the specified name.

    Parameters:
      `aGroupName` - the name of the group containing the parameter
      `aParamName` - the name of the parameter to look up
    Returns:
      the value of the parameter with the given name. The caller is expected to know the data type of the parameter. Returns `null` if the parameter does not exist or has not been assigned a value.

  - ### getConfigurationGroupNames

    String[] getConfigurationGroupNames()
    Gets the names of all configuration parameter groups.
    Returns:
      an array containing the names of all configuration groups that exist for this component. Returns an empty array if no groups are declared.

  - ### getConfigParameterNames

    String[] getConfigParameterNames(String aGroup)
    Gets the names of all configuration parameters in the specified group.
    Parameters:
      `aGroup` - the group name
    Returns:
      an array containing the names of all configuration parameters declared in `aGroup`. Note that this does include parameters with null values. Returns an empty array if there are none (including if the group does not exist).

  - ### getConfigParameterNames

    String[] getConfigParameterNames()
    Gets the names of all configuration parameters that are not declared in a group.
    Returns:
      an array containing the names of all configuration parameters not declared in any group. Returns an empty array if there are none.

  - ### getSharedSettingValue

    String getSharedSettingValue(String name) throws ResourceConfigurationException
    Get the value of a shared configuration parameter from the external override settings.
    Parameters:
      `name` - - the name of the parameter
    Returns:
      - the value found in the shared settings file(s), or null if missing.
    Throws:
      `ResourceConfigurationException` - if the value references an undefined parameter, or the value is an array

  - ### getSharedSettingArray

    String[] getSharedSettingArray(String name) throws ResourceConfigurationException
    Get the array of values for a shared configuration parameter from the external override settings.
    Parameters:
      `name` - - the name of the parameter
    Returns:
      - an array of values found in the shared settings file(s), or null if missing.
    Throws:
      `ResourceConfigurationException` - if the value references an undefined parameter, or the value is not an array

  - ### getSharedSettingNames

    String[] getSharedSettingNames()
    Get the names of all the external override settings available.
    Returns:
      - an array containing the names of all the external override settings.

  - ### getExternalOverrides

    Settings getExternalOverrides()
    Gets the `Settings` used for external parameter overrides
    Returns:
      the Settings object

  - ### getLogger

    Logger getLogger()
    Gets the `Logger` to which log output will be sent. UIMA components should use this facility rather than writing to their own log files (or to stdout).
    Returns:
      an instance of a logger for use by this annotator.

  - ### getInstrumentationFacility

    InstrumentationFacility getInstrumentationFacility()
    Gets the `InstrumentationFacility` that a component can use to record information about its performance.
    Returns:
      an instance of the instrumentation facility

  - ### getResourceURL

    URL getResourceURL(String aKey) throws ResourceAccessException
    Retrieves the URL to the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    Note that if the URL contains spaces may be encoded as %20. The `URL.getPath()` method does NOT decode these sequences, therefore it is not safe to call `getResourceURL().getPath()` and attempt to use the result as a file path. Instead, you may use `getResourceURI(String)` or `getResourceFilePath(String)`.

    For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
    Returns:
      the `URL` at which the named resource is located, `null` if the named resource could not be found.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getResourceURI

    URI getResourceURI(String aKey) throws ResourceAccessException
    Retrieves the URI to the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    This method is safer than `getResourceURL(String)` in its treatment of file paths containing spaces. This is because the `URI.getPath()` does perform URL decoding of that path (decoding %20 sequences to spaces) whereas `URL.getPath()` does not.

    For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
    Returns:
      the `URI` at which the named resource is located, `null` if the named resource could not be found.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getResourceFilePath

    String getResourceFilePath(String aKey) throws ResourceAccessException
    Retrieves the absolute file path to the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    This only works if the resource is a local file. If the resource is not a local file (for example, it could be an `http` URL, then an exception will be thrown.

    URL decoding will be done on the file path, so it is safe to use this method for file paths that contain spaces. For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
    Returns:
      the absolute file path at which the named resource is located, `null` if the named resource could not be found.
    Throws:
      `ResourceAccessException` - if the resource is not a local file, or if a failure occurs in accessing the resource

  - ### getResourceAsStream

    InputStream getResourceAsStream(String aKey) throws ResourceAccessException
    Retrieves an InputStream for reading from the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
    Returns:
      an `InputStream` for reading from the named resource, `null` if the named resource could not be found. It is the caller's responsibility to close this stream once it is no longer needed.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getResourceObject

    Object getResourceObject(String aKey) throws ResourceAccessException
    Retrieves the named resource object. This can be used to acquire references to external resources. The resource should be declared in the <externalResourceDependencies> section of the descriptor.
    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
    Returns:
      the object bound to `aName`, `null` if none.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getResourceURL

    URL getResourceURL(String aKey, String[] aParams) throws ResourceAccessException
    Retrieves the URL to the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    Note that if the URL contains spaces they may be encoded as %20. The `URL.getPath()` method does NOT decode these sequences, therefore it is not safe to call `getResourceURL().getPath()` and attempt to use the result as a file path. Instead, you may use `getResourceURI(String)` or `getResourceFilePath(String)`.

    For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    This version of this method takes an array of parameters used to further identify the resource. This can be used, for example, with resources that vary depending on the language of the document being analyzed, such as when the <fileLanguageResourceSpecifier> element is used in the component descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
      `aParams` - parameters used to further identify the resource. When used to identify the language for a <fileLanguageResourceSpecifier>, this array should contain a single element, the ISO language code for the language of the document (e.g. "en", "de").
    Returns:
      the `URL` at which the named resource is located, `null` if the named resource could not be found.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getResourceURI

    URI getResourceURI(String aKey, String[] aParams) throws ResourceAccessException
    Retrieves the URI to the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    This method is safer than `getResourceURL(String)` in its treatment of file paths containing spaces. This is because the `URI.getPath()` does perform URL decoding of that path (decoding %20 sequences to spaces) whereas `URL.getPath()` does not.

    For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    This version of this method takes an array of parameters used to further identify the resource. This can be used, for example, with resources that vary depending on the language of the document being analyzed, such as when the <fileLanguageResourceSpecifier> element is used in the component descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
      `aParams` - parameters used to further identify the resource. When used to identify the language for a <fileLanguageResourceSpecifier>, this array should contain a single element, the ISO language code for the language of the document (e.g. "en", "de").
    Returns:
      the `URI` at which the named resource is located, `null` if the named resource could not be found.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getResourceFilePath

    String getResourceFilePath(String aKey, String[] aParams) throws ResourceAccessException
    Retrieves the absolute file path to the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    This only works if the resource is a local file. If the resource is not a local file (for example, it could be an `http` URL, then an exception will be thrown.

    URL decoding will be done on the file path, so it is safe to use this method for file paths that contain spaces.

    For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    This version of this method takes an array of parameters used to further identify the resource. This can be used, for example, with resources that vary depending on the language of the document being analyzed, such as when the <fileLanguageResourceSpecifier> element is used in the component descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
      `aParams` - parameters used to further identify the resource. When used to identify the language for a <fileLanguageResourceSpecifier>, this array should contain a single element, the ISO language code for the language of the document (e.g. "en", "de").
    Returns:
      the absolute file path at which the named resource is located, `null` if the named resource could not be found.
    Throws:
      `ResourceAccessException` - if the resource is not a local file, or if a failure occurs in accessing the resource

  - ### getResourceAsStream

    InputStream getResourceAsStream(String aKey, String[] aParams) throws ResourceAccessException
    Retrieves an InputStream for reading from the named resource. This can be used, for example, to locate configuration or authority files. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    For backwards compatibility, if the key is not declared as a resource dependency, it is looked up directly in the `data path` and the class path. However, this usage is deprecated and support may be dropped in future versions. ALL external resource dependencies should be declared in the descriptor.

    This version of this method takes an array of parameters used to further identify the resource. This can be used, for example, with resources that vary depending on the language of the document being analyzed, such as when the <fileLanguageResourceSpecifier> element is used in the component descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should bd declared in the <externalResourceDependencies> section of the descriptor.
      `aParams` - parameters used to further identify the resource. When used to identify the language for a <fileLanguageResourceSpecifier>, this array should contain a single element, the ISO language code for the language of the document (e.g. "en", "de").
    Returns:
      an `InputStream` for reading from the named resource, `null` if the named resource could not be found. It is the caller's responsibility to close this stream once it is no longer needed.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getResourceObject

    Object getResourceObject(String aKey, String[] aParams) throws ResourceAccessException
    Retrieves the named resource object. This can be used to acquire references to external resources. The resource should be declared in the <externalResourceDependencies> section of the descriptor.

    This version of this method takes an array of parameters used to further identify the resource. This can be used, for example, with resources that vary depending on the language of the document being analyzed, such as when the <fileLanguageResourceSpecifier> element is used in the component descriptor.

    Parameters:
      `aKey` - the key by which the resource is identified. This key should be declared in the <externalResourceDependencies> section of the descriptor.
      `aParams` - parameters used to further identify the resource. When used to identify the language for a <fileLanguageResourceSpecifier>, this array should contain a single element, the ISO language code for the language of the document (e.g. "en", "de").
    Returns:
      the object bound to `aName`, `null` if none.
    Throws:
      `ResourceAccessException` - if a failure occurs in accessing the resource

  - ### getDataPath

    @Deprecated String getDataPath()
    Deprecated.
    Use `getDataPathElements()` instead.
    Gets the data path used to locate resources. This path may contain more than one directory, separated by the System `path.separator` character (; on windows, : on UNIX).

    This method is intended to be used only for integration of legacy or third-party components that have their own resource management facility. If possible, it is recommended that you use the `getResoureXXX` methods instead.

    Returns:
      the data path

  - ### getDataPathElements

    List<String> getDataPathElements()
    Gets the data path elements used to resolve relative paths.
    Returns:
      the data path elements

  - ### getSession

    Session getSession()
    Returns the Session object, which can be used to store data that pertains to a particular client session. All data that must persist across requests must be stored in the Session object and NOT in component instance variables. In some service deployments, a single component instance may serve multiple clients. In that case, the service wrapper may provide a different Session object for each client, and this method would return the appropriate Session object for the component to use for the current call.

    Note that Session support is NOT implemented in any of the service wrappers (e.g. Vinci) currently provided in the UIMA SDK.

    Returns:
      the current Session object

  - ### mapToSofaID

    @Deprecated SofaID mapToSofaID(String aSofaName)
    Deprecated.
    As of v2.0, annotators no longer need to explicitly call this method. CAS views can now be obtained directly by the method `CAS.getView(String)`, and the framework will automatically do the necessary Sofa mappings.
    Retrieve actual sofa ID given a symbolic name
    Parameters:
      `aSofaName` - this component's name for a SofA
    Returns:
      absolute SofA ID

  - ### mapSofaIDToComponentSofaName

    String mapSofaIDToComponentSofaName(String aSofaID)
    Retrieve the sofa name as known to the component given an absolute Sofa ID.
    Parameters:
      `aSofaID` - absolute SofA ID
    Returns:
      this component's name for that SofA

  - ### getSofaMappings

    @Deprecated SofaID[] getSofaMappings()
    Deprecated.
    As of v2.0, annotators no longer need to explicitly call this method. CAS views can now be obtained directly by the method `CAS.getView(String)`, and the framework will automatically do the necessary Sofa mappings.
    Returns:
      array of SofaID objects containing mapping of component sofa name to absolute sofa id

  - ### getEmptyCas

    <T extends AbstractCas> T getEmptyCas(Class<T> aCasInterface)
    Get an empty CAS. This method can only be called from CAS Multipliers, and typically a CAS Multiplier would call this indirectly through its `CasMultiplier_ImplBase.getEmptyCAS()` or `JCasMultiplier_ImplBase.getEmptyJCas()` method.

    This method may maintain a pool of CASes and may block if none are currently available.

    Type Parameters:
      `T` - the type of the CAS interface (CAS or JCas)
    Parameters:
      `aCasInterface` - the specific CAS interface that the component wants to use (e.g. CAS or JCas). Must specify a subtype of `AbstractCas`.
    Returns:
      an empty CAS. This will be an implementation of `aCasInterface`. The CAS will be unlocked (can be reset) but will have switched Class Loaders if needed.