Package org.apache.uima.resource

# Interface ResourceManager

All Known Subinterfaces:
  `ResourceManagerPearWrapper`

All Known Implementing Classes:
  `ResourceManager_impl`

public interface ResourceManager
A `ResourceManager` holds a collection of `Resource` objects, each registered under a specified key.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `destroy()`
  Frees all resources held by this ResourceManager, and marks the ResourceManager as having been destroyed.
  `CasManager`
  `getCasManager()`
  Gets the CasManager, which manages the creation and pooling of CASes.
  `String`
  `getDataPath()`
  Deprecated.
  Use `getDataPathElements()` instead.
  `List<String>`
  `getDataPathElements()`
  Gets the data path elements used to resolve relative paths.
  `ClassLoader`
  `getExtensionClassLoader()`
  Returns the UIMA extension class loader.
  `List<Object>`
  `getExternalResources()`
  `Map<String,XMLizable>`
  `getImportCache()`
  Deprecated.
  Intended just for internal use.
  `Object`
  `getResource(String aName)`
  Gets the instance of the implementation object for a resource that has been registered under the specified name.
  `Object`
  `getResource(String aName, String[] aParams)`
  Returns one of two kinds of objects (or null): - an instance of the implementation object for a resource, that has been loaded with a DataResource resource produced by the resource given the aParms - (if there is no implementation defined for this resource) returns an instance of the DataResource, itself, produced by the resource given the aParms An example of a parameterized Resource is a dictionary whose data depend on a specified language identifier.
  `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.
  `<N> Class<N>`
  `getResourceClass(String aName)`
  Gets the Class of the Resource that will be returned by a call to `getResource(String)` or `getResource(String,String[])`.
  `URL`
  `getResourceURL(String aKey)`
  Retrieves the URL to the named resource.
  `URL`
  `getResourceURL(String aKey, String[] aParams)`
  Retrieves the URL to the named resource.
  `void`
  `initializeExternalResources(ResourceManagerConfiguration aConfiguration, String aQualifiedContextName, Map<String,Object> aAdditionalParams)`
  Initializes all external resources declared in a ResourceCreationSpecifier.
  `<N> Class<N>`
  `loadUserClass(String name)`
  Loads a user class using either the UIMA extension class loader (if specified) or the ThreadLocal Context Class Loader (if available) or the loader the UIMA framework is running in.
  `void`
  `resolveAndValidateResourceDependencies(ExternalResourceDependency[] aDependencies, String aQualifiedContextName)`
  Resolves a component's external resource dependencies (bindings) using this resource manager.
  `URL`
  `resolveRelativePath(String aRelativePath)`
  Attempts to resolve a relative path to an absolute path using the same mechanism that the ResourceManager uses to find resources -- a lookup in the datapath followed by a lookup in the classpath.
  `void`
  `setCasManager(CasManager aCasManager)`
  Sets the CasManager, which manages the creation and pooling of CASes.
  `void`
  `setDataPath(String aPath)`
  Deprecated.
  Use `setDataPathElements(java.lang.String...)` instead.
  `void`
  `setDataPathElements(File... aElements)`
  Sets the data path elements used to resolve relative paths.
  `void`
  `setDataPathElements(String... aElements)`
  Sets the data path elements used to resolve relative paths.
  `default void`
  `setExtensionClassLoader(ClassLoader classLoader, boolean resolveResources)`
  Set an extension class loader into the Resource Manager
  `void`
  `setExtensionClassPath(ClassLoader parent, String classpath, boolean resolveResource)`
  Sets the classpath for the UIMA extension ClassLoader and specifies if the extension ClassLoader should also be used to resolve resources.
  `void`
  `setExtensionClassPath(String classpath, boolean resolveResource)`
  Sets the classpath for the UIMA extension ClassLoader and specifies if the extension ClassLoader should also be used to resolve resources.

- ## Method Details

  - ### getDataPath

    @Deprecated String getDataPath()
    Deprecated.
    Use `getDataPathElements()` instead.
    Gets the data path used to resolve relative paths. More than one directory may be specified by separating them with the System `path.separator` character (; on windows, : on UNIX).
    Returns:
      the data path

  - ### getDataPathElements

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

  - ### setDataPath

    @Deprecated void setDataPath(String aPath) throws MalformedURLException
    Deprecated.
    Use `setDataPathElements(java.lang.String...)` instead.
    Sets the data path used to resolve relative paths. More than one directory may be specified by separating them with the System `path.separator` character (; on windows, : on UNIX). Elements of this path may be absolute or relative file paths.
    Parameters:
      `aPath` - the data path
    Throws:
      `MalformedURLException` - if an element of the path is neither a valid URL or a valid file path

  - ### setDataPathElements

    void setDataPathElements(String... aElements) throws MalformedURLException
    Sets the data path elements used to resolve relative paths. Elements of this path may be absolute or relative file paths.
    Parameters:
      `aElements` - the data path
    Throws:
      `MalformedURLException` - if an element of the path is neither a valid URL or a valid file path

  - ### setDataPathElements

    void setDataPathElements(File... aElements) throws MalformedURLException
    Sets the data path elements used to resolve relative paths. Elements of this path may be absolute or relative file paths.
    Parameters:
      `aElements` - the data path
    Throws:
      `MalformedURLException` - if an element of the path is neither a valid URL or a valid file path

  - ### resolveRelativePath

    URL resolveRelativePath(String aRelativePath) throws MalformedURLException
    Attempts to resolve a relative path to an absolute path using the same mechanism that the ResourceManager uses to find resources -- a lookup in the datapath followed by a lookup in the classpath.
    Parameters:
      `aRelativePath` - a relative URL or file path
    Returns:
      the absolute URL of an actual file in the datapath or classpath, null if no file matching `aRelativePath` is found.
    Throws:
      `MalformedURLException` - if the path cannot be converted to a URL

  - ### getResource

    Object getResource(String aName) throws ResourceAccessException
    Gets the instance of the implementation object for a resource that has been registered under the specified name.
    Parameters:
      `aName` - the name of the resource to retrieve
    Returns:
      the instance of the implementation object for the resource, registered under `aName`, `null` if none exists.
    Throws:
      `ResourceAccessException` - if the requested resource could not be initialized. A common cause is that it requires parameters and the `getResource(String,String[])` method should have been called instead of this method.
      `ResourceAccessException` - tbd

  - ### getResource

    Object getResource(String aName, String[] aParams) throws ResourceAccessException
    Returns one of two kinds of objects (or null): - an instance of the implementation object for a resource, that has been loaded with a DataResource resource produced by the resource given the aParms - (if there is no implementation defined for this resource) returns an instance of the DataResource, itself, produced by the resource given the aParms An example of a parameterized Resource is a dictionary whose data depend on a specified language identifier. If the implementation object class exists, but no instance has been created (yet) for the particular data resource corresponding to the parameters, then this method will create and register a new instance and call its load() api using the data resource corresponding to the parameters, and return that.
    Parameters:
      `aName` - the name of the parameterized resource to retrieve
      `aParams` - the parameters determining which particular instance is returned and specifying a particular DataResource instance to use in initializing the implementation of the resource (if there is an implementation). If there is no implementation, the DataResource instance produced from the named Resource given these parameters is returned instead.
    Returns:
      one of two kinds of objects (or null): an instance of the requested implementation of the named resource where that instance has been initialized by calling its load method with the DataResource instance produced from the Resource given aParams, or, (if the named resource has no implementation) the DataResource instance corresponding to the named Resource, given aParams, or if no resource with this name exists, `null`.
    Throws:
      `ResourceAccessException` - if there is a resource registered under `aName` but it could not be instantiated for the specified parameters.

  - ### getResourceClass

    <N> Class<N> getResourceClass(String aName)
    Gets the Class of the Resource that will be returned by a call to `getResource(String)` or `getResource(String,String[])`. For those resource specifications which include an implementation class, this call returns that class.
    Type Parameters:
      `N` - The generic type for the returned class
    Parameters:
      `aName` - the name of a resource
    Returns:
      the Class for the resource named `aName`, `null` if there is no resource registered under that name.

  - ### 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.
    Parameters:
      `aKey` - the key by which the resource is identified. If this key was declared in the <externalResourceDependencies> section of the descriptor, then the resource manager is used to locate the resource. If not, the key is assumed to be the resource name and is looked up in the `data path` or in the class path using `ClassLoader.getResource(String)`.
    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

  - ### getResourceAsStream

    InputStream getResourceAsStream(String aKey) throws ResourceAccessException
    Retrieves an InputStream for reading from the named resource. This can be used, for example, to read configuration or authority files.
    Parameters:
      `aKey` - the key by which the resource is identified. If this key was declared in the <externalResourceDependencies> section of the annotator's descriptor, then the resource manager is used to locate the resource. If not, the key is assumed to be the resource name and is looked up in the `data path` or in the class path using `ClassLoader.getResource(String)`.
    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

  - ### 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. 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.
    Parameters:
      `aKey` - the key by which the resource is identified. If this key was declared in the <externalResourceDependencies> section of the annotator's descriptor, then the resource manager is used to locate the resource. If not, the key is assumed to be the resource name and is looked up in the `data path` or in the class path using `ClassLoader.getResource(String)`.
      `aParams` - parameters used to further identify the resource
    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

  - ### 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 read configuration or authority files. 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.
    Parameters:
      `aKey` - the key by which the resource is identified. If this key was declared in the <externalResourceDependencies> section of the annotator's descriptor, then the resource manager is used to locate the resource. If not, the key is assumed to be the resource name and is looked up in the `data path` or in the class path using `ClassLoader.getResource(String)`.
      `aParams` - parameters used to further identify the resource
    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

  - ### initializeExternalResources

    void initializeExternalResources(ResourceManagerConfiguration aConfiguration, String aQualifiedContextName, Map<String,Object> aAdditionalParams) throws ResourceInitializationException
    Initializes all external resources declared in a ResourceCreationSpecifier. Multi-threading: may be called on multiple threads. Initialization should be done once, on the first call External resources have a Container class representing the resource, which are instances of Resource. This may act as the implementation class, or they may also have a separately specified implementation class, which may or may not implement Resource. As part of the initialization of the Container class, by default, External Resource Bindings are processed to hook them up with defined External Resources, using the default implementation of resolveAndValidateResourceDependencies.
    Parameters:
      `aConfiguration` - the ResourceManagerConfiguration containing resource declarations and bindings
      `aQualifiedContextName` - qualified name of UimaContext for the component (e.g. analysis engine) that is declaring these external resources
      `aAdditionalParams` - additional parameters to be passed to resource initialize methods
    Throws:
      `ResourceInitializationException` - if an initialization failure occurs

  - ### resolveAndValidateResourceDependencies

    void resolveAndValidateResourceDependencies(ExternalResourceDependency[] aDependencies, String aQualifiedContextName) throws ResourceInitializationException
    Resolves a component's external resource dependencies (bindings) using this resource manager. The default implementation has special defaulting logic: If a binding specifies a non-existing resource, an attempt is made to interpret the key as a file name, looked up using the current context for relative path resolution. - If successfully found, a FileResourceSpecifier is created using the file and used as the implementing class. If no resource can be found at all, then unless the dependency is marked "optional", an ResourceInitializationException is thrown. Multi-threading: may be called on multiple threads, repeatedly for the same set of resources. Implementations should recognize this and skip repeated resolutions.
    Parameters:
      `aDependencies` - declarations of a component's dependencies on external resources
      `aQualifiedContextName` - qualified name of UimaContext for the component (e.g. analysis engine) that is declaring these dependencies
    Throws:
      `ResourceInitializationException` - if a required dependency is not satisfied

  - ### setExtensionClassPath

    void setExtensionClassPath(String classpath, boolean resolveResource) throws MalformedURLException
    Sets the classpath for the UIMA extension ClassLoader and specifies if the extension ClassLoader should also be used to resolve resources.
    Parameters:
      `classpath` - extension ClassLoader classpath
      `resolveResource` - if true ClassLoad resolves resources
    Throws:
      `MalformedURLException` - if a malformed URL has occurred in the classpath string.

  - ### setExtensionClassPath

    void setExtensionClassPath(ClassLoader parent, String classpath, boolean resolveResource) throws MalformedURLException
    Sets the classpath for the UIMA extension ClassLoader and specifies if the extension ClassLoader should also be used to resolve resources. Also allows a parent ClassLoader to be specified.
    Parameters:
      `parent` - parent ClassLoader for the extension ClassLoader
      `classpath` - extension ClassLoader classpath
      `resolveResource` - if true ClassLoad resolves resources
    Throws:
      `MalformedURLException` - if a malformed URL has occurred in the classpath string.

  - ### setExtensionClassLoader

    default void setExtensionClassLoader(ClassLoader classLoader, boolean resolveResources)
    Set an extension class loader into the Resource Manager
    Parameters:
      `classLoader` - the loader to use. If this is an instance of UIMAClassLoader, it is used directly; otherwise, a new UIMAClassLoader with no classpath, having the classLoader as a parent is created and used.
      `resolveResources` - true to also use this to resolve resources

  - ### getExtensionClassLoader

    ClassLoader getExtensionClassLoader()
    Returns the UIMA extension class loader.
    Returns:
      ClassLoader - returns the UIMA extension class loader of null if it is not available.

  - ### getCasManager

    CasManager getCasManager()
    Gets the CasManager, which manages the creation and pooling of CASes.
    Returns:
      the CasManager

  - ### setCasManager

    void setCasManager(CasManager aCasManager)
    Sets the CasManager, which manages the creation and pooling of CASes. This method does not normally need to be called by an application. It allows a custom CAS Manager implementation to be substituted for the default one, which may be useful when embedding UIMA in other middleware where a different CAS Manager implementation may be desired.

    This method can only be called once, and must be called before creating any AnalysisEngines that use this ResourceManager. An Exception will be thrown if this method is called twice or is called after `getCasManager()` has already been called (which happens during AE initialization).

    Parameters:
      `aCasManager` - CAS Manager instance to plug in

  - ### getImportCache

    @Deprecated Map<String,XMLizable> getImportCache()
    Deprecated.
    Intended just for internal use.
    Gets a cache of imported descriptors, so that the parsed objects can be reused if the same URL is imported more than once.
    Returns:
      A map from absolute URL to the XMLizable object that was parsed from that URL

  - ### loadUserClass

    <N> Class<N> loadUserClass(String name) throws ClassNotFoundException
    Loads a user class using either the UIMA extension class loader (if specified) or the ThreadLocal Context Class Loader (if available) or the loader the UIMA framework is running in. If the class is not found in the ThreadLocal COntext Class Loader, then the loader the UIMA framework is running in will be searched.
    Type Parameters:
      `N` - generic class of class
    Parameters:
      `name` - the class to load
    Returns:
      the class
    Throws:
      `ClassNotFoundException` - -

  - ### destroy

    void destroy()
    Frees all resources held by this ResourceManager, and marks the ResourceManager as having been destroyed. A destroyed ResourceManager will throw an exception if an attempt is made to continue using it. Resources managed by a ResourceManager include all of the external shared Resources. If there is an extension class loader in use, it will be closed. Any class loaders (including PEAR class loaders) that might use this as a parent will be affected by this closure. Any streams opened using getResourceAsStream will also be closed. The Resources managed by this manager will have their destroy() methods called, as part of the execution of this API. The framework does not call this method; it is up to the containing application to decide if and when a ResourceManager instance should be destroyed. This is because the containing application is the only knowledgeable source; for example a single ResourceManager might be used for multiple UIMA Pipelines.

  - ### getExternalResources

    List<Object> getExternalResources()
    Returns:
      a List of External Shared Resource instances instantiated by this Resource Manager. For parameterized resources, those which have been asked for (having unique parameter sets) are included.