Class CasCreationUtils


  • public class CasCreationUtils
    extends java.lang.Object
    Utilities for creating and setting up CASes. Also includes utilities for merging CAS type systems.
    • Constructor Detail

      • CasCreationUtils

        public CasCreationUtils()
    • Method Detail

      • createCas

        public static CAS createCas​(AnalysisEngineDescription aDescription)
                             throws ResourceInitializationException
        Creates a new CAS instance for an Analysis Engine. This works for both primitive and aggregate analysis engines.
        Parameters:
        aDescription - description of the analysis engine that will process this CAS. This is used to set up the CAS's type system and indexes.
        Returns:
        a new CAS instance
        Throws:
        ResourceInitializationException - if CAS creation fails
      • createCas

        public static CAS createCas​(AnalysisEngineDescription aDescription,
                                    java.util.Properties aPerformanceTuningSettings)
                             throws ResourceInitializationException
        Creates a new CAS instance for an Analysis Engine. This works for both primitive and aggregate analysis engines.
        Parameters:
        aDescription - description of the analysis engine that will process this CAS. This is used to set up the CAS's type system and indexes.
        aPerformanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
        Returns:
        a new CAS instance
        Throws:
        ResourceInitializationException - if CAS creation fails
      • createCas

        public static CAS createCas​(TypeSystemDescription aTypeSystem,
                                    TypePriorities aTypePriorities,
                                    FsIndexDescription[] aFsIndexes,
                                    java.util.Properties aPerformanceTuningSettings)
                             throws ResourceInitializationException
        Creates a new CAS instance.
        Parameters:
        aTypeSystem - type system to install in the CAS
        aTypePriorities - type priorities to install in the CAS
        aFsIndexes - indexes to install in the CAS
        aPerformanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
        Returns:
        a new CAS instance
        Throws:
        ResourceInitializationException - if CAS creation fails
      • createCas

        public static CAS createCas​(TypeSystemDescription aTypeSystem,
                                    TypePriorities aTypePriorities,
                                    FsIndexDescription[] aFsIndexes,
                                    java.util.Properties aPerformanceTuningSettings,
                                    ResourceManager aResourceManager)
                             throws ResourceInitializationException
        Creates a new CAS instance.
        Parameters:
        aTypeSystem - type system to install in the CAS
        aTypePriorities - type priorities to install in the CAS
        aFsIndexes - indexes to install in the CAS
        aPerformanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
        aResourceManager - the resource manager
        Returns:
        a new CAS instance
        Throws:
        ResourceInitializationException - if CAS creation fails
      • createCas

        public static CAS createCas​(TypeSystem aTypeSystem,
                                    TypePriorities aTypePriorities,
                                    FsIndexDescription[] aFsIndexes,
                                    java.util.Properties aPerformanceTuningSettings)
                             throws ResourceInitializationException
        Creates a new CAS instance that reuses an existing type system. Using this method allows several CASes to all share the exact same type system object.
        Parameters:
        aTypeSystem - type system to install in the CAS
        aTypePriorities - type priorities to install in the CAS
        aFsIndexes - indexes to install in the CAS
        aPerformanceTuningSettings - the settings for performance tuning
        Returns:
        a new CAS instance
        Throws:
        ResourceInitializationException - if CAS creation fails
      • createCas

        public static CAS createCas​(TypeSystem aTypeSystem,
                                    TypePriorities aTypePriorities,
                                    FsIndexDescription[] aFsIndexes,
                                    java.util.Properties aPerformanceTuningSettings,
                                    ResourceManager aResourceManager)
                             throws ResourceInitializationException
        Creates a new CAS instance that reuses an existing type system. Using this method allows several CASes to all share the exact same type system object.
        Parameters:
        aTypeSystem - type system to install in the CAS
        aTypePriorities - type priorities to install in the CAS
        aFsIndexes - indexes to install in the CAS
        aPerformanceTuningSettings - the settings for performance tuning
        aResourceManager - resource manager, which is used to set the JCas ClassLoader for the new CAS
        Returns:
        a new CAS instance
        Throws:
        ResourceInitializationException - if CAS creation fails
      • createCas

        public static CAS createCas​(CasDefinition casDef,
                                    java.util.Properties performanceTuningSettings)
                             throws ResourceInitializationException
        Create a CAS from a CAS Definition.
        Parameters:
        casDef - completely describes the CAS to be created
        performanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
        Returns:
        a new CAS matching the given CasDefinition
        Throws:
        ResourceInitializationException - if CAS creation fails
      • createCas

        public static CAS createCas​(CasDefinition casDef,
                                    java.util.Properties performanceTuningSettings,
                                    TypeSystem typeSystem)
                             throws ResourceInitializationException
        Create a CAS from a CAS Definition, but reuse the provided TypeSystem object.
        Parameters:
        casDef - completely describes the CAS to be created
        performanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
        typeSystem - type system object to reuse
        Returns:
        a new CAS matching the given CasDefinition
        Throws:
        ResourceInitializationException - if CAS creation fails
      • convertData2TypeSystem

        public static TypeSystemDescription convertData2TypeSystem​(CasData aCasData)
        Extracts a TypeSystem definition from a CasData.
        Parameters:
        aCasData - the CAS Data from which to extract the type system
        Returns:
        a description of a TypeSystem to which the CAS Data conforms
      • mergeTypeSystems

        public static TypeSystemDescription mergeTypeSystems​(java.util.Collection<? extends TypeSystemDescription> aTypeSystems)
                                                      throws ResourceInitializationException
        Merges several TypeSystemDescriptions into one. Also resolves imports in the TypeSystemDescription objects.
        Parameters:
        aTypeSystems - a collection of TypeSystems to be merged
        Returns:
        a new TypeSystemDescription that is the result of merging all of the type systems together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeTypeSystems

        public static TypeSystemDescription mergeTypeSystems​(java.util.Collection<? extends TypeSystemDescription> aTypeSystems,
                                                             ResourceManager aResourceManager)
                                                      throws ResourceInitializationException
        Merges several TypeSystemDescriptions into one. Also resolves imports in the TypeSystemDescription objects.
        Parameters:
        aTypeSystems - a collection of TypeSystems to be merged
        aResourceManager - Resource Manager to use to locate type systems imported by name
        Returns:
        a new TypeSystemDescription that is the result of merging all of the type systems together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeTypeSystems

        public static TypeSystemDescription mergeTypeSystems​(java.util.Collection<? extends TypeSystemDescription> aTypeSystems,
                                                             ResourceManager aResourceManager,
                                                             java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> aOutputMergedTypes)
                                                      throws ResourceInitializationException
        Merges several TypeSystemDescriptions into one. Also resolves imports in the TypeSystemDescription objects.

        This version of this method takes an argument aOutputMergedTypes, which this method will populate with the names and descriptor locations of any types whose definitions have been merged from multiple non-identical sources. That is, types that are declared more than once, with different (but compatible) sets of features in each declaration, or with different (but compatible) supertypes.

        Parameters:
        aTypeSystems - a collection of TypeSystems to be merged
        aResourceManager - Resource Manager to use to locate type systems imported by name
        aOutputMergedTypes - A Map that this method will populate with information about the set of types whose definitions were merged from multiple non-identical sources. The keys in the Map will be the type names (Strings) and the values will be {link Set}s containing Descriptor URLs (Strings) where those types are declared. You may pass null if you are not interested in this information.
        Returns:
        a new TypeSystemDescription that is the result of merging all of the type systems together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeDelegateAnalysisEngineTypeSystems

        public static TypeSystemDescription mergeDelegateAnalysisEngineTypeSystems​(AnalysisEngineDescription aAggregateDescription)
                                                                            throws ResourceInitializationException
        Merges the Type Systems of each component within an aggregate Analysis Engine, producing a single combined Type System.
        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        Returns:
        a new TypeSystemDescription that is the result of merging all of the delegate AE type systems together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeDelegateAnalysisEngineTypeSystems

        public static TypeSystemDescription mergeDelegateAnalysisEngineTypeSystems​(AnalysisEngineDescription aAggregateDescription,
                                                                                   ResourceManager aResourceManager)
                                                                            throws ResourceInitializationException
        Merges the Type Systems of each component within an aggregate Analysis Engine, producing a single combined Type System.

        This version of this method takes an argument aOutputMergedTypeNames, to which this method will add the names of any types whose definitions have been merged from multiple non-identical sources. That is, types that are declared more than once, with different (but compatible) sets of features in each declaration, or with different (but compatible) supertypes.

        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        aResourceManager - ResourceManager instance used to resolve imports
        Returns:
        a new TypeSystemDescription that is the result of merging all of the delegate AE type systems together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeDelegateAnalysisEngineTypeSystems

        public static TypeSystemDescription mergeDelegateAnalysisEngineTypeSystems​(AnalysisEngineDescription aAggregateDescription,
                                                                                   ResourceManager aResourceManager,
                                                                                   java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> aOutputMergedTypes)
                                                                            throws ResourceInitializationException
        Merges the Type Systems of each component within an aggregate Analysis Engine, producing a single combined Type System.

        This version of this method takes an argument aOutputMergedTypes, which this method will populate with the names and descriptor locations of any types whose definitions have been merged from multiple non-identical sources. That is, types that are declared more than once, with different (but compatible) sets of features in each declaration, or with different (but compatible) supertypes.

        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        aResourceManager - ResourceManager instance used to resolve imports
        aOutputMergedTypes - A Map that this method will populate with information about the set of types whose definitions were merged from multiple non-identical sources. The keys in the Map will be the type names (Strings) and the values will be {link Set}s containing Descriptor URLs (Strings) where those types are declared. You may pass null if you are not interested in this information. *
        Returns:
        a new TypeSystemDescription that is the result of merging all of the delegate AE type systems together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeFsIndexes

        public static FsIndexCollection mergeFsIndexes​(java.util.List<? extends FsIndexCollection> aFsIndexCollections,
                                                       ResourceManager aResourceManager)
                                                throws ResourceInitializationException
        Merges a List of FsIndexCollections into a single FsIndexCollection object.
        Parameters:
        aFsIndexCollections - list of FsIndexCollection objects
        aResourceManager - ResourceManager instance to use to resolve imports
        Returns:
        a merged FsIndexCollection object
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeDelegateAnalysisEngineFsIndexCollections

        public static FsIndexCollection mergeDelegateAnalysisEngineFsIndexCollections​(AnalysisEngineDescription aAggregateDescription)
                                                                               throws ResourceInitializationException
        Merges the FS Index Collections of each component within an aggregate Analysis Engine, producing a single combined FS Index Collection.
        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        Returns:
        a new FsIndexCollection that is the result of merging all of the delegate AE FsIndexCollections together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeDelegateAnalysisEngineFsIndexCollections

        public static FsIndexCollection mergeDelegateAnalysisEngineFsIndexCollections​(AnalysisEngineDescription aAggregateDescription,
                                                                                      ResourceManager aResourceManager)
                                                                               throws ResourceInitializationException
        Merges the FS Index Collections of each component within an aggregate Analysis Engine, producing a single combined FS Index Collection.
        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        aResourceManager - ResourceManager instance used to resolve imports
        Returns:
        a new FsIndexCollection that is the result of merging all of the delegate AE FsIndexCollections together
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • mergeTypePriorities

        public static TypePriorities mergeTypePriorities​(java.util.List<? extends TypePriorities> aTypePriorities,
                                                         ResourceManager aResourceManager)
                                                  throws ResourceInitializationException
        Merges a List of TypePriorities into a single TypePriorities object.
        Parameters:
        aTypePriorities - list of TypePriorities objects
        aResourceManager - ResourceManager instance to use to resolve imports
        Returns:
        a merged TypePriorities object
        Throws:
        ResourceInitializationException - if an import could not be resolved
      • mergeDelegateAnalysisEngineTypePriorities

        public static TypePriorities mergeDelegateAnalysisEngineTypePriorities​(AnalysisEngineDescription aAggregateDescription)
                                                                        throws ResourceInitializationException
        Merges the Type Priorities of each component within an aggregate Analysis Engine, producing a single combined TypePriorities object.
        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        Returns:
        a new TypePriorities object that is the result of merging all of the delegate AE TypePriorities together
        Throws:
        ResourceInitializationException - if an incompatibility exists
      • mergeDelegateAnalysisEngineTypePriorities

        public static TypePriorities mergeDelegateAnalysisEngineTypePriorities​(AnalysisEngineDescription aAggregateDescription,
                                                                               ResourceManager aResourceManager)
                                                                        throws ResourceInitializationException
        Merges the Type Priorities of each component within an aggregate Analysis Engine, producing a single combined TypePriorities object.
        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        aResourceManager - ResourceManager instance used to resolve imports
        Returns:
        a new TypePriorities object that is the result of merging all of the delegate AE TypePriorities together
        Throws:
        ResourceInitializationException - if an incompatibility exists
      • mergeDelegateAnalysisEngineMetaData

        public static ProcessingResourceMetaData mergeDelegateAnalysisEngineMetaData​(AnalysisEngineDescription aAggregateDescription,
                                                                                     ResourceManager aResourceManager,
                                                                                     java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> aOutputMergedTypes,
                                                                                     java.util.Map<java.lang.String,​? super java.lang.Exception> aOutputFailedRemotes)
                                                                              throws ResourceInitializationException
        Merges the Type Systems, Type Priorities, and FS Indexes of each component within an aggregate Analysis Engine.

        This version of this method takes an argument aOutputMergedTypes, which this method will populate with the names and descriptor locations of any types whose definitions have been merged from multiple non-identical sources. That is, types that are declared more than once, with different (but compatible) sets of features in each declaration, or with different (but compatible) supertypes.

        Parameters:
        aAggregateDescription - an aggregate Analysis Engine description
        aResourceManager - ResourceManager instance used to resolve imports
        aOutputMergedTypes - A Map that this method will populate with information about the set of types whose definitions were merged from multiple non-identical sources. That is, types that are declared more than once, with different (but compatible) sets of features in each declaration, or with different (but compatible) supertypes. The keys in the Map will be the type names (Strings) and the values will be {link Set}s containing Descriptor URLs (Strings) where those types are declared. You may pass null if you are not interested in this information.
        aOutputFailedRemotes - If this parameter is non-null, and if a remote AE could not be contacted, then an entry will be added to this map. The key will be the context name (e.g., /myDelegate1/nestedRemoteDelegate) of the failed remote, and the value will be the Exception that occurred. If this parameter is null, an exception will be thrown if a remote AE could not be contacted.
        Returns:
        an object containing the merged TypeSystem, TypePriorities, and FS Index definitions.
        Throws:
        ResourceInitializationException - if an incompatibility exists or if an import could not be resolved
      • subsumes

        protected static boolean subsumes​(java.lang.String aType1Name,
                                          java.lang.String aType2Name,
                                          java.util.Map<java.lang.String,​? extends TypeDescription> aNameMap)
        Determines whether one type subsumes another.
        Parameters:
        aType1Name - name of first type
        aType2Name - name of second type
        aNameMap - Map from type names to TypeDescriptions
        Returns:
        true if and only if the type named aType1Name subsumes the type named aType2Name according to the information given in the aNameMap.
      • getMetaDataList

        public static java.util.List<ProcessingResourceMetaData> getMetaDataList​(java.util.Collection<? extends MetaDataObject> aComponentDescriptionOrMetaData,
                                                                                 ResourceManager aResourceManager,
                                                                                 java.util.Map<java.lang.String,​? super java.lang.Exception> aOutputFailedRemotes)
                                                                          throws ResourceInitializationException
        Gets a list of ProcessingResourceMetadata objects from a list containing either ResourceSpecifiers, ProcessingResourceMetadata objects, or subparts of ProcessingResourceMetadata objects (type systems, indexes, or type priorities). Subparts will be wrapped inside a ProcessingResourceMetadata object. All objects will be cloned, so that further processing (such as import resolution) does not affect the caller.

        If you pass this method objects of type AnalysisEngineDescription, CollectionReaderDescription, CasInitializerDescription, or CasConsumerDescription, it will not instantiate the components. It will just extract the type system information from the descriptor. For any other kind of ResourceSpecifier, it will call UIMAFramework.produceResource(org.apache.uima.resource.ResourceSpecifier, Map). For example, if a URISpecifier is passed, a remote connection will be established and the service will be queries for its metadata. An exception will be thrown if the connection can not be opened. Note that this last kind of lookup may be expensive (calling produceResource, which in turn may query remote connections etc.). Because of this, a cache is maintained for these, (because some scenarios end up requesting the same metadata multiple times, in rapid succession). Because remote resource may become available, the cache entries are removed 30 seconds after they are created. This also reclaims space from the cache.

        Parameters:
        aComponentDescriptionOrMetaData - a collection of ResourceSpecifier, ProcessingResourceMetaData, TypeSystemDescription, FsIndexCollection, or TypePriorities objects.
        aResourceManager - used to resolve delegate analysis engine imports
        aOutputFailedRemotes - If this parameter is non-null, and if a remote AE could not be contacted, then the context name (e.g. /myDelegate1/nestedRemoteDelegate) of the failed remote will be added to this collection. If this parameter is null, an exception will be thrown if a remote AE could not be contacted.
        Returns:
        a List containing the ProcessingResourceMetaData objects containing all of the information in all of the objects in aComponentDescriptionOrMetaData (including all components of aggregate AnalysisEngines)
        Throws:
        ResourceInitializationException - if a failure occurs because an import could not be resolved