org.apache.uima.UimaContext Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.uima;
import java.io.InputStream;
import java.net.URI;
import java.net.URL;
import java.util.List;
import org.apache.uima.cas.AbstractCas;
import org.apache.uima.cas.CAS;
import org.apache.uima.cas.SofaID;
import org.apache.uima.resource.ResourceAccessException;
import org.apache.uima.resource.ResourceConfigurationException;
import org.apache.uima.resource.Session;
import org.apache.uima.util.InstrumentationFacility;
import org.apache.uima.util.Logger;
import org.apache.uima.util.Settings;
/**
* 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 {@link org.apache.uima.cas.CAS}). Examples include:
*
* - Configuration Parameters
* - Logging & Instrumentation Facilities
* - Access to External Analysis Resources, such as dictionary files
*
*/
public interface UimaContext {
/**
* 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.
*
* @param aParamName
* the name of the parameter to look up
*
* @return 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.
*/
Object getConfigParameterValue(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
* {@link org.apache.uima.resource.metadata.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.
*
* @param aGroupName
* the name of the group containing the parameter
* @param aParamName
* the name of the parameter to look up
* @return 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.
*/
Object getConfigParameterValue(String aGroupName, String aParamName);
/**
* Gets the names of all configuration parameter groups.
*
* @return an array containing the names of all configuration groups that exist for this
* component. Returns an empty array if no groups are declared.
*/
String[] getConfigurationGroupNames();
/**
* Gets the names of all configuration parameters in the specified group.
*
* @param aGroup
* the group name
* @return 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).
*/
String[] getConfigParameterNames(String aGroup);
/**
* Gets the names of all configuration parameters that are not declared in a group.
*
* @return an array containing the names of all configuration parameters not declared in any
* group. Returns an empty array if there are none.
*/
String[] getConfigParameterNames();
/**
* Get the value of a shared configuration parameter from the external override settings.
*
* @param name
* - the name of the parameter
* @return - 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
*/
String getSharedSettingValue(String name) throws ResourceConfigurationException;
/**
* Get the array of values for a shared configuration parameter from the external override
* settings.
*
* @param name
* - the name of the parameter
* @return - 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
*/
String[] getSharedSettingArray(String name) throws ResourceConfigurationException;
/**
* Get the names of all the external override settings available.
*
* @return - an array containing the names of all the external override settings.
*/
String[] getSharedSettingNames();
/**
* Gets the Settings used for external parameter overrides
*
* @return the Settings object
*/
Settings getExternalOverrides();
/**
* 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).
*
* @return an instance of a logger for use by this annotator.
*/
Logger getLogger();
/**
* Gets the InstrumentationFacility that a component can use to record information
* about its performance.
*
* @return an instance of the instrumentation facility
*/
InstrumentationFacility getInstrumentationFacility();
/**
* 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 {@link 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 {@link #getResourceURI(String)} or {@link #getResourceFilePath(String)}.
*
* For backwards compatibility, if the key is not declared as a resource dependency, it is looked
* up directly in the {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
* @return 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
*/
URL getResourceURL(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 {@link #getResourceURL(String)} in its treatment of file paths
* containing spaces. This is because the {@link URI#getPath()} does perform URL decoding of that
* path (decoding %20 sequences to spaces) whereas {@link URL#getPath()} does not.
*
* For backwards compatibility, if the key is not declared as a resource dependency, it is looked
* up directly in the {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
* @return 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
*/
URI getResourceURI(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 {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
*
* @return 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
*/
String getResourceFilePath(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 {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
* @return 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
*/
InputStream getResourceAsStream(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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
*
* @return the object bound to aName, null if none.
*
* @throws ResourceAccessException
* if a failure occurs in accessing the resource
*/
Object getResourceObject(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 they may be encoded as %20. The {@link 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 {@link #getResourceURI(String)} or {@link #getResourceFilePath(String)}.
*
* For backwards compatibility, if the key is not declared as a resource dependency, it is looked
* up directly in the {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
* @param 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").
*
* @return 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
*/
URL getResourceURL(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 {@link #getResourceURL(String)} in its treatment of file paths
* containing spaces. This is because the {@link URI#getPath()} does perform URL decoding of that
* path (decoding %20 sequences to spaces) whereas {@link URL#getPath()} does not.
*
* For backwards compatibility, if the key is not declared as a resource dependency, it is looked
* up directly in the {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
* @param 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").
*
* @return 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
*/
URI getResourceURI(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 {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
* @param 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").
*
* @return 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
*/
String getResourceFilePath(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 {@link #getDataPathElements() 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.
*
* @param aKey
* the key by which the resource is identified. This key should bd declared in the
* <externalResourceDependencies> section of the descriptor.
* @param 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").
*
* @return 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
*/
InputStream getResourceAsStream(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.
*
* @param aKey
* the key by which the resource is identified. This key should be declared in the
* <externalResourceDependencies> section of the descriptor.
* @param 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").
*
* @return the object bound to aName, null if none.
*
* @throws ResourceAccessException
* if a failure occurs in accessing the resource
*/
Object getResourceObject(String aKey, String[] aParams) throws ResourceAccessException;
/**
* 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.
*
* @return the data path
* @deprecated Use {@link #getDataPathElements()} instead.
*/
@Deprecated
String getDataPath();
/**
* Gets the data path elements used to resolve relative paths.
*
* @return the data path elements
*/
List getDataPathElements();
/**
* 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.
*
* @return the current Session object
*/
Session getSession();
/**
* Retrieve actual sofa ID given a symbolic name
*
* @param aSofaName
* this component's name for a SofA
* @return absolute SofA ID
*
* @deprecated As of v2.0, annotators no longer need to explicitly call this method. CAS views can
* now be obtained directly by the method {@link CAS#getView(String)}, and the
* framework will automatically do the necessary Sofa mappings.
*/
@Deprecated
SofaID mapToSofaID(String aSofaName);
/**
* Retrieve the sofa name as known to the component given an absolute Sofa ID.
*
* @param aSofaID
* absolute SofA ID
* @return this component's name for that SofA
*/
String mapSofaIDToComponentSofaName(String aSofaID);
/**
* @return array of SofaID objects containing mapping of component sofa name to absolute sofa id
*
* @deprecated As of v2.0, annotators no longer need to explicitly call this method. CAS views can
* now be obtained directly by the method {@link CAS#getView(String)}, and the
* framework will automatically do the necessary Sofa mappings.
*/
@Deprecated
SofaID[] getSofaMappings();
/**
* Get an empty CAS. This method can only be called from CAS Multipliers, and typically a CAS
* Multiplier would call this indirectly through its
* {@link org.apache.uima.analysis_component.CasMultiplier_ImplBase#getEmptyCAS()} or
* {@link org.apache.uima.analysis_component.JCasMultiplier_ImplBase#getEmptyJCas()} method.
*
* This method may maintain a pool of CASes and may block if none are currently available.
*
* @param aCasInterface
* the specific CAS interface that the component wants to use (e.g. CAS or JCas). Must
* specify a subtype of {@link AbstractCas}.
* @param
* the type of the CAS interface (CAS or JCas)
*
* @return 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.
*/
T getEmptyCas(Class aCasInterface);
}