Package org.apache.uima

Class UIMAFramework

  • Direct Known Subclasses:
    UIMAFramework_impl
    public abstract class UIMAFramework
extends java.lang.Object
    This is an application's main interface point to the UIMA Framework. Static methods on this class allow the application to create instances of UIMA components.

    This class also provides the ability to change the underlying UIMA implementation. All UIMA implementations must provide a subclass of UIMAFramework as part of their distribution. If you wish to use a UIMA implementation other than the default reference implementation, set the System property uima.framework_impl to the fully qualified class name of the UIMAFramework subclass that you wish to use. Note that this must be done prior to loading this class. If the uima.framework_impl property has not been set when this class is loaded, the default reference implementation will be used.

    • Field Detail

      • CAS_INITIAL_HEAP_SIZE

        public static final java.lang.String CAS_INITIAL_HEAP_SIZE
        Key to be used in the Properties object returned by getDefaultPerformanceTuningProperties(). The value of this key represents the size of the initial CAS heap in terms of the number of cells (32 bits per cell).
        See Also:
        Constant Field Values

      • PROCESS_TRACE_ENABLED

        public static final java.lang.String PROCESS_TRACE_ENABLED
        Key to be used in the Properties object returned by getDefaultPerformanceTuningProperties(). The value of this key indicates whether the ProcessTrace mechanism (which tracks the time spent in individual components of an aggregate AE or CPE) is enabled. A value of "true" (case insensitive) enables ProcessTrace; any other value disables process trace.
        See Also:
        Constant Field Values

      • SOCKET_KEEPALIVE_ENABLED

        public static final java.lang.Object SOCKET_KEEPALIVE_ENABLED
        Key to be used in the Properties object returned by getDefaultPerformanceTuningProperties(). The value of this key indicates whether socket KeepAlive should be turned on (currently implemented only for Vinci clients). The default is true. A value of "false" (case insensitive) for this property disables the keepAlive; any other value leaves the default setting of true.
        See Also:
        Socket.setKeepAlive(boolean)

      • JCAS_CACHE_ENABLED

        public static final java.lang.String JCAS_CACHE_ENABLED
        Key to be used in the Properties object returned by getDefaultPerformanceTuningProperties(). The value of this key indicates whether the JCas object cache should be used (significant memory overhead, but may have performance benefits). The default is true. A value of "false" (case insensitive) for this property disables the cache; any other value leaves the default setting of true.
        See Also:
        Constant Field Values

      • newContextResourceManager

        public static final java.lang.ThreadLocal<ResourceManager> newContextResourceManager

      • newContextConfigManager

        public static final java.lang.ThreadLocal<ConfigurationManager> newContextConfigManager

    • Constructor Detail

      • UIMAFramework

        public UIMAFramework()

    • Method Detail

      • _getDefaultPerformanceTuningProperties

        protected abstract java.util.Properties _getDefaultPerformanceTuningProperties()
        To be implemented by subclasses; this should return a Properties object representing the default performance tuning settings for the framework. It must return a new Properties object each time it is called.
        Returns:
        default performance tuning properties

      • getVersionString

        public static java.lang.String getVersionString()
        Gets the framework implementation's version number as a string. This will be the major version number, minor version number, and build revision in that order, separated by dots.
        Returns:
        the version number string

      • getMajorVersion

        public static short getMajorVersion()
        Gets the major version number of the framework implementation.
        Returns:
        the major version number

      • getMinorVersion

        public static short getMinorVersion()
        Gets the minor version number of the framework implementation.
        Returns:
        the minor version number

      • getBuildRevision

        public static short getBuildRevision()
        Gets the build revision number of the framework implementation.
        Returns:
        the build revision number

      • getResourceFactory

        public static CompositeResourceFactory getResourceFactory()
        Get a reference to the ResourceFactory. Most applications do not need to deal with the ResourceFactory - instead one of the static produce methods on this class may be used to create Resources.

        The framework's Resource Factory always implements CompositeResourceFactory. A composite resource factory produces resources by delegating to other ResourceFactory objects. Developers to register their own specialized ResourceFactory objects by calling the CompositeResourceFactory.registerFactory(Class,ResourceFactory) method.

        Returns:
        the ResourceFactory to be used by the application.

      • getXMLParser

        public static XMLParser getXMLParser()
        Get a reference to the UIMA XMLParser, which is used to parse ResourceSpecifier objects from their XML representations.
        Returns:
        the XMLParser to be used by the application.

      • newCollectionProcessingManager

        public static CollectionProcessingManager newCollectionProcessingManager()
        Creates a new CollectionProcessingManager instance. The CollectionProcessingManager facilitates the development of applications that process collections of entities using an AnalysisEngine.
        Returns:
        a new CollectionProcessingManager instance to be used by the application.

      • newCollectionProcessingManager

        public static CollectionProcessingManager newCollectionProcessingManager​(ResourceManager aResourceManager)
        Creates a new CollectionProcessingManager instance. The CollectionProcessingManager facilitates the development of applications that process collections of entities using an AnalysisEngine.
        Parameters:
        aResourceManager - the ResourceManager to be used by this CPM. If not specified, the default one returned by newDefaultResourceManager() will be used.
        Returns:
        a new CollectionProcessingManager instance to be used by the application.

      • produceResource

        public static Resource produceResource​(java.lang.Class<? extends Resource> aResourceClass,
                                       ResourceSpecifier aSpecifier,
                                       java.util.Map<java.lang.String,​java.lang.Object> aAdditionalParams)
                                throws ResourceInitializationException
        Produces an appropriate Resource instance of a specified class from a ResourceSpecifier. The ResourceSpecifier may either specify how to construct a new instance or how to locate an existing instance.
        Parameters:
        aResourceClass - a subclass of Resource to be produced.
        aSpecifier - an object that specifies how to acquire an instance of a Resource.
        aAdditionalParams - a Map containing additional parameters to pass to the Resource.initialize(ResourceSpecifier,Map) method. May be null if there are no parameters. Parameter names are defined as constants on the AnalysisEngine, and Resource. Furthermore, the entry under the key Resource.PARAM_PERFORMANCE_TUNING_SETTINGS is a map which may contain settings with keys defined as constants here UIMAFramework interfaces. For example this can be used to set performance-tuning settings as described in getDefaultPerformanceTuningProperties().
        Returns:
        a Resource instance. This will be a subclass of aResourceClass.
        Throws:
        ResourceInitializationException - if a failure occurred during production of the resource.

      • produceResource

        public static Resource produceResource​(java.lang.Class<? extends Resource> aResourceClass,
                                       ResourceSpecifier aSpecifier,
                                       ResourceManager aResourceManager,
                                       java.util.Map<java.lang.String,​java.lang.Object> aAdditionalParams)
                                throws ResourceInitializationException
        Produces an appropriate Resource instance of a specified class from a ResourceSpecifier. The ResourceSpecifier may either specify how to construct a new instance or how to locate an existing instance.
        Parameters:
        aResourceClass - a subclass of Resource to be produced.
        aSpecifier - an object that specifies how to acquire an instance of a Resource.
        aResourceManager - the ResourceManager to be used by this analysis engine. If not specified, the default one returned by newDefaultResourceManager() will be used.
        aAdditionalParams - a Map containing additional parameters to pass to the Resource.initialize(ResourceSpecifier,Map) method. May be null if there are no parameters. Parameter names are defined as constants on the AnalysisEngine, and Resource. Furthermore, the entry under the key Resource.PARAM_PERFORMANCE_TUNING_SETTINGS is a map which may contain settings with keys defined as constants here UIMAFramework interfaces. For example this can be used to set performance-tuning settings as described in getDefaultPerformanceTuningProperties().
        Returns:
        a Resource instance. This will be a subclass of aResourceClass.
        Throws:
        ResourceInitializationException - if a failure occurred during production of the resource.

      • produceAnalysisEngine

        public static AnalysisEngine produceAnalysisEngine​(ResourceSpecifier aSpecifier)
                                            throws ResourceInitializationException
        Produces an AnalysisEngine instance from a ResourceSpecifier. The ResourceSpecifier may either specify how to construct a new instance or how to locate an existing instance.

        The AnalysisEngine returned from this method is not guaranteed to be able to process multiple simultaneous requests. See produceAnalysisEngine(ResourceSpecifier,int,int) for more information.

        Parameters:
        aSpecifier - an object that specifies how to acquire an instance of a Resource. This must specify a subclass of AnalysisEngine.
        Returns:
        an AnalysisEngine instance.
        Throws:
        ResourceInitializationException - if a failure occurred during production of the resource.

      • produceAnalysisEngine

        public static AnalysisEngine produceAnalysisEngine​(ResourceSpecifier aSpecifier,
                                                   int aMaxSimultaneousRequests,
                                                   int aTimeoutPeriod)
                                            throws ResourceInitializationException
        Produces an AnalysisEngine instance from a ResourceSpecifier. The ResourceSpecifier may either specify how to construct a new instance or how to locate an existing instance.

        This version of produceAnalysisEngine allows the convenient creation of AnalysisEngines that can handle multiple simultaneous requests. Using this method is equivalent to using produceAnalysisEngine(ResourceSpecifier,Map) and including values for AnalysisEngine.PARAM_NUM_SIMULTANEOUS_REQUESTS and AnalysisEngine.PARAM_TIMEOUT_PERIOD in the parameter map.

        Parameters:
        aSpecifier - an object that specifies how to acquire an instance of a Resource. This must specify a subclass of AnalysisEngine.
        aMaxSimultaneousRequests - the number of simultaneous requests that this AnalysisEngine should be able to process. The value for this parameter should be chosen careful - see the JavaDocs for AnalysisEngine.PARAM_NUM_SIMULTANEOUS_REQUESTS.
        aTimeoutPeriod - - when the number of simultaneous requests exceeds aMaxSimultaneousReqeusts, additional requests will wait for other requests to finish. This parameter determines the maximum number of milliseconds that a new request should wait before throwing an exception - a value of 0 will cause them to wait forever. See the JavaDocs for AnalysisEngine.PARAM_TIMEOUT_PERIOD.
        Returns:
        an AnalysisEngine instance.
        Throws:
        ResourceInitializationException - if a failure occurred during production of the resource.

      • produceCasConsumer

        public static CasConsumer produceCasConsumer​(ResourceSpecifier aSpecifier)
                                      throws ResourceInitializationException
        Produces a CasConsumer instance from a ResourceSpecifier. The ResourceSpecifier may either specify how to construct a new instance or how to locate an existing instance.
        Parameters:
        aSpecifier - an object that specifies how to acquire an instance of a Resource. This must specify a subclass of CasConsumer.
        Returns:
        a CasConsumer instance.
        Throws:
        ResourceInitializationException - if a failure occurred during production of the resource.

      • produceCollectionReader

        public static CollectionReader produceCollectionReader​(ResourceSpecifier aSpecifier)
                                                throws ResourceInitializationException
        Produces a CollectionReader instance from a ResourceSpecifier. The ResourceSpecifier may either specify how to construct a new instance or how to locate an existing instance.
        Parameters:
        aSpecifier - an object that specifies how to acquire an instance of a Resource. This must specify a subclass of CollectionReader.
        Returns:
        a CollectionReader instance.
        Throws:
        ResourceInitializationException - if a failure occurred during production of the resource.

      • produceCasInitializer

        @Deprecated
public static CasInitializer produceCasInitializer​(ResourceSpecifier aSpecifier)
                                            throws ResourceInitializationException
        Deprecated.
        As of v2.0, CAS Initializers are deprecated. A component that performs an operation like HTML detagging should instead be implemented as a "multi-Sofa" annotator. See org.apache.uima.examples.XmlDetagger for an example.
        Produces a CasInitializer instance from a ResourceSpecifier. The ResourceSpecifier may either specify how to construct a new instance or how to locate an existing instance.
        Parameters:
        aSpecifier - an object that specifies how to acquire an instance of a Resource. This must specify a subclass of CasInitializer.
        Returns:
        a CasInitializer instance.
        Throws:
        ResourceInitializationException - if a failure occurred during production of the resource.

      • getLogger

        public static Logger getLogger()
        Gets the Logger used by the UIMA framework. An application won't generally write to this logger, although nothing is stopping it from doing so.

        In the UIMA SDK, the logger is implemented using the Java 1.4 logger as a back end. If you want to configure the logger, for example to specify the location of the log file and the logging level, you should use the standard Java 1.4 logger properties or the java.util.logging APIs. See the section "Specifying the Logging Configuration" in the Annotator and Analysis Engine Developer's Guide chapter of the UIMA documentation for more information.

        Returns:
        the default Logger used by UIMA components

      • getLogger

        public static Logger getLogger​(java.lang.Class<?> component)
        Gets the Logger used by a particular Class, for example an Annotator. An application won't generally write to this logger, although nothing is stopping it from doing so.

        In the UIMA SDK, the logger is implemented using the Java 1.4 logger as a back end. If you want to configure the logger, for example to specify the location of the log file and the logging level, you should use the standard Java 1.4 logger properties or the java.util.logging APIs. See the section "Specifying the Logging Configuration" in the Annotator and Analysis Engine Developer's Guide chapter of the UIMA documentation for more information.

        Parameters:
        component - the Class for a component, for example an Annotator or CAS Consumer
        Returns:
        the Logger used by the specified component class

      • newLogger

        public static Logger newLogger()
        Creates a new Logger, which can be passed for example to the AnalysisEngine.setLogger(Logger) method in order to have separate Analysis Engine instances used separate loggers.
        Returns:
        a new Logger instance
        See Also:
        getLogger()

      • newTimer

        public static UimaTimer newTimer()
        Creates a new UimaTimer, which is used to collect performance statistics for UIMA components.
        Returns:
        a new Timer instance

      • newDefaultResourceManagerPearWrapper

        public static ResourceManager newDefaultResourceManagerPearWrapper()
        Gets a new instance of the default ResourceManagerPearWrapper used by this implementation.
        Returns:
        a new ResourceManagerPearWrapper to be used by the application.

      • newConfigurationManager

        public static ConfigurationManager newConfigurationManager()
        Gets a new instance of the ConfigurationManager used by this implementation. This will be used by Resources to manage access to their configuration parameters.
        Returns:
        a new ConfigurationManager to be used by the application.

      • newUimaContext

        public static UimaContextAdmin newUimaContext​(Logger aLogger,
                                              ResourceManager aResourceManager,
                                              ConfigurationManager aConfigManager)
        Gets a new instance of a UimaContext. Applications do not generally need to call this method.
        Parameters:
        aLogger - the logger that will be returned by this UimaContext's getLogger() method.
        aResourceManager - the ResourceManager that will be used by this UimaContext to locate and access external resource.
        aConfigManager - the ConfigurationManager that will be used by this UimaContext to manage Configuration Parameter settings.
        Returns:
        a new UIMA Context to be used by the application.

      • getDefaultPerformanceTuningProperties

        public static java.util.Properties getDefaultPerformanceTuningProperties()
        Gets the default performance tuning settings for the framework. Advanced users can tweak the framework by modifying these properties and passing the modified Properties object into the produceTAE(ResourceSpecifier,Map) or produceCollectionProcessingEngine(CpeDescription,Map) methods by putting it into the aAdditionalParams map under the key Resource.PARAM_PERFORMANCE_TUNING_SETTINGS. For example, the following code set the initial heap size allocated in the CAS to 100,000: 
         Properties uimaPerfProps = UIMAFramework.getDefaultPerformanceTuningProperties();
 uimaPerfProps.setProperty(UIMAFramework.CAS_INITIAL_HEAP_SIZE, "100000");
 HashMap params = new HashMap();
 params.put(Resource.PARAM_PERFORMANCE_TUNING_SETTINGS, uimaPerfProps);
 AnalysisEngine ae = UIMAFramework.produceAnalysisEngine(specifier, params);

        Valid keys for the Properties object returned by this method are specified as constants on this interface.

        Returns:
        the default set of performance tuning properties. A new object is returned each time this method is called, so changes made to the returned objects will not affect other callers.

      • getInstance

        protected static UIMAFramework getInstance()
        Gets the UIMAFramework instance currently in use.
        Returns:
        the UIMAFramework instance currently in use

      • _getMajorVersion

        protected abstract short _getMajorVersion()
        To be implemented by subclasses; this should return the major version number of this implementation.
        Returns:
        the major version number

      • _getMinorVersion

        protected abstract short _getMinorVersion()
        To be implemented by subclasses; this should return the minor version number of this implementation.
        Returns:
        the minor version number

      • _initialize

        protected abstract void _initialize()
                             throws java.lang.Exception
        To be implemented by subclasses; called from this class's static initializer to complete initialization of the singleton instance. This initialization is done outside the constructor so that the getInstance() method can be used during initialization.
        Throws:
        java.lang.Exception - if initialization fails

      • _getBuildRevision

        protected abstract short _getBuildRevision()
        To be implemented by subclasses; this should return the build revision number of this implementation.
        Returns:
        the build revision number

      • _getResourceFactory

        protected abstract CompositeResourceFactory _getResourceFactory()
        To be implemented by subclasses; this should return a reference to the ResourceFactory used by this implementation, which must implement CompositeResourceFactory.
        Returns:
        the ResourceFactory to be used by the application

      • _getResourceSpecifierFactory

        protected abstract ResourceSpecifierFactory _getResourceSpecifierFactory()
        To be implemented by subclasses; this should return a reference to the ResourceSpecifierFactory used by this implementation.
        Returns:
        the ResourceSpecifierFactory to be used by the application.

      • _getXMLParser

        protected abstract XMLParser _getXMLParser()
        To be implemented by subclasses; this should return a reference to the UIMA XMLParser used by this implementation.
        Returns:
        the XMLParser to be used by the application.

      • _newCollectionProcessingManager

        protected abstract CollectionProcessingManager _newCollectionProcessingManager​(ResourceManager aResourceManager)
        To be implemented by subclasses; this should create a new instance of a class implementing CollectionProcessingManager.
        Parameters:
        aResourceManager - the ResourceManager to be used by the CPM
        Returns:
        a new CollectionProcessingManager to be used by the application.

      • _getLogger

        protected abstract Logger _getLogger()
        To be implemented by subclasses; this should return a reference to the default UIMA Logger used by this implementation.
        Returns:
        the default Logger used by this implementation

      • _getLogger

        protected abstract Logger _getLogger​(java.lang.Class<?> component)
        To be implemented by subclasses; this should return a reference to the UIMA Logger of the specified source class.
        Parameters:
        component - the class to get the logger for
        Returns:
        the Logger of the specified source class

      • _newLogger

        protected abstract Logger _newLogger()
        To be implemented by subclasses; this should return a new UIMA Logger instance.
        Returns:
        a new Logger instance

      • _newTimer

        protected abstract UimaTimer _newTimer()
        To be implemented by subclasses; this should return a new UIMA UimaTimer instance.
        Returns:
        a new Timer instance

      • _newDefaultResourceManager

        protected abstract ResourceManager _newDefaultResourceManager()
        To be implemented by subclasses; this should return a new instance of the default ResourceManager used by this implementation.
        Returns:
        a new ResourceManager to be used by the application.

      • _newDefaultResourceManagerPearWrapper

        protected abstract ResourceManager _newDefaultResourceManagerPearWrapper()
        To be implemented by subclasses; this should return a new instance of the default ResourceManagerPearWrapper used by this implementation.
        Returns:
        a new ResourceManagerPearWrapper to be used by the application.

      • _newConfigurationManager

        protected abstract ConfigurationManager _newConfigurationManager()
        To be implemented by subclasses; this should return a new instance of the default ConfigurationManager used by this implementation.
        Returns:
        a new ConfigurationManager to be used by the application.

      • _newUimaContext

        protected abstract UimaContextAdmin _newUimaContext()
        To be implemented by subclasses; this should return a new instance of the default UimaContextAdmin used by this implementation.
        Returns:
        a new UimaContextAdmin to be used by the application.