/*
* 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.util.HashMap;
import java.util.Map;
import java.util.Properties;
import org.apache.uima.analysis_engine.AnalysisEngine;
import org.apache.uima.analysis_engine.AnalysisEngineManagement.State;
import org.apache.uima.analysis_engine.TextAnalysisEngine;
import org.apache.uima.analysis_engine.impl.AnalysisEngineManagementImpl;
import org.apache.uima.collection.CasConsumer;
import org.apache.uima.collection.CasInitializer;
import org.apache.uima.collection.CollectionProcessingEngine;
import org.apache.uima.collection.CollectionProcessingManager;
import org.apache.uima.collection.CollectionReader;
import org.apache.uima.collection.metadata.CpeDescription;
import org.apache.uima.resource.ConfigurationManager;
import org.apache.uima.resource.Resource;
import org.apache.uima.resource.ResourceInitializationException;
import org.apache.uima.resource.ResourceManager;
import org.apache.uima.resource.ResourceSpecifier;
import org.apache.uima.util.Logger;
import org.apache.uima.util.UimaTimer;
import org.apache.uima.util.XMLParser;
/**
* 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.
* <p>
* This class also provides the ability to change the underlying UIMA implementation. All UIMA
* implementations must provide a subclass of <code>UIMAFramework</code> as part of their
* distribution. If you wish to use a UIMA implementation other than the default reference
* implementation, set the System property <code>uima.framework_impl</code> to the fully qualified
* class name of the <code>UIMAFramework</code> subclass that you wish to use. Note that this must
* be done prior to loading this class. If the <code>uima.framework_impl</code> property has not
* been set when this class is loaded, the default reference implementation will be used.
*
*
*/
public abstract class UIMAFramework {
/**
* Key to be used in the Properties object returned by
* {@link #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).
*/
public static final String CAS_INITIAL_HEAP_SIZE = "cas_initial_heap_size";
/**
* Key to be used in the Properties object returned by
* {@link #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.
*/
public static final String PROCESS_TRACE_ENABLED = "process_trace_enabled";
/**
* Key to be used in the Properties object returned by
* {@link #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 java.net.Socket#setKeepAlive(boolean)
*/
public static final Object SOCKET_KEEPALIVE_ENABLED = "socket_keepalive_enabled";
/**
* Key to be used in the Properties object returned by
* {@link #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.
*/
public static final String JCAS_CACHE_ENABLED = "jcas_cache_enabled";
/**
* 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.
*
* @return default performance tuning properties
*/
protected abstract Properties _getDefaultPerformanceTuningProperties();
/**
* The singleton instance of <code>UIMAFramework</code> used by this application. The value of
* this field is determined by the <code>uima.framework_impl</code> System property. During this
* class's static initializer, a new instance of whatever class is named by this property will be
* created. If no value for this property is set, the default reference implementation ({@link org.apache.uima.impl.UIMAFramework_impl})
* will be used.
*/
private static final UIMAFramework mInstance;
/**
* The name of the <code>UIMAFramework</code> subclass for the UIMA reference implementation. An
* instance of this class will be created if the application does not supply a custom framework
* implementation.
*/
private static final String REF_IMPL_CLASS_NAME = "org.apache.uima.impl.UIMAFramework_impl";
/**
* 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.
*
* @return the version number string
*/
public static String getVersionString() {
return "" + getMajorVersion() + "." + getMinorVersion() + "." + getBuildRevision();
}
/**
* Gets the major version number of the framework implementation.
*
* @return the major version number
*/
public static short getMajorVersion() {
return getInstance()._getMajorVersion();
}
/**
* Gets the minor version number of the framework implementation.
*
* @return the minor version number
*/
public static short getMinorVersion() {
return getInstance()._getMinorVersion();
}
/**
* Gets the build revision number of the framework implementation.
*
* @return the build revision number
*/
public static short getBuildRevision() {
return getInstance()._getBuildRevision();
}
/**
* Get a reference to the <code>ResourceFactory</code>. Most applications do not need to deal
* with the <code>ResourceFactory</code> - instead one of the static <code>produce</code>
* methods on this class may be used to create Resources.
* <p>
* The framework's Resource Factory always implements {@link CompositeResourceFactory}. A
* composite resource factory produces resources by delegating to other {@link ResourceFactory}
* objects. Developers to register their own specialized <code>ResourceFactory</code> objects by
* calling the {@link CompositeResourceFactory#registerFactory(Class,ResourceFactory)} method.
*
* @return the <code>ResourceFactory</code> to be used by the application.
*/
public static CompositeResourceFactory getResourceFactory() {
return getInstance()._getResourceFactory();
}
/**
* Get a reference to the {@link ResourceSpecifierFactory}. This factory is used when
* constructing {@link ResourceSpecifier}s from scratch.
* <p>
*
* @return the <code>ResourceSpecifierFactory</code> to be used by the application.
*/
public static ResourceSpecifierFactory getResourceSpecifierFactory() {
return getInstance()._getResourceSpecifierFactory();
}
/**
* Get a reference to the UIMA {@link XMLParser}, which is used to parse
* {@link ResourceSpecifier} objects from their XML representations.
*
* @return the <code>XMLParser</code> to be used by the application.
*/
public static XMLParser getXMLParser() {
return getInstance()._getXMLParser();
}
/**
* Creates a new {@link CollectionProcessingManager} instance. The
* <code>CollectionProcessingManager</code> facilitates the development of applications that
* process collections of entities using an {@link AnalysisEngine}.
*
* @return a new <code>CollectionProcessingManager</code> instance to be used by the
* application.
*/
public static CollectionProcessingManager newCollectionProcessingManager() {
return getInstance()._newCollectionProcessingManager(null);
}
/**
* Creates a new {@link CollectionProcessingManager} instance. The
* <code>CollectionProcessingManager</code> facilitates the development of applications that
* process collections of entities using an {@link AnalysisEngine}.
*
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this CPM. If not specified, the
* default one returned by {@link #newDefaultResourceManager()} will be used.
*
* @return a new <code>CollectionProcessingManager</code> instance to be used by the
* application.
*/
public static CollectionProcessingManager newCollectionProcessingManager(
ResourceManager aResourceManager) {
return getInstance()._newCollectionProcessingManager(aResourceManager);
}
/**
* Produces an appropriate <code>Resource</code> instance from a <code>ResourceSpecifier</code>.
* The <code>ResourceSpecifier</code> may either specify how to construct a new instance or how
* to locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. For example this can be used to set performance-tuning
* settings as described in {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>Resource</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static Resource produceResource(ResourceSpecifier aSpecifier, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return produceResource(Resource.class, aSpecifier, aAdditionalParams);
}
/**
* Produces an appropriate <code>Resource</code> instance of a specified class from a
* <code>ResourceSpecifier</code>. The <code>ResourceSpecifier</code> may either specify how
* to construct a new instance or how to locate an existing instance.
*
* @param aResourceClass
* a subclass of <code>Resource</code> to be produced.
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. For example this can be used to set performance-tuning
* settings as described in {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>Resource</code> instance. This will be a subclass of
* <code>aResourceClass</code>.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static Resource produceResource(Class<? extends Resource> aResourceClass, ResourceSpecifier aSpecifier,
Map<String, Object> aAdditionalParams) throws ResourceInitializationException {
Resource resource = getResourceFactory().produceResource(aResourceClass, aSpecifier,
aAdditionalParams);
if (resource == null) {
throw new ResourceInitializationException(ResourceInitializationException.DO_NOT_KNOW_HOW,
new Object[] { aResourceClass.getName(), aSpecifier.getSourceUrlString() });
}
return resource;
}
/**
* Produces an appropriate <code>Resource</code> instance of a specified class from a
* <code>ResourceSpecifier</code>. The <code>ResourceSpecifier</code> may either specify how
* to construct a new instance or how to locate an existing instance.
*
* @param aResourceClass
* a subclass of <code>Resource</code> to be produced.
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this analysis engine. If not
* specified, the default one returned by {@link #newDefaultResourceManager()} will be
* used.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. For example this can be used to set performance-tuning
* settings as described in {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>Resource</code> instance. This will be a subclass of
* <code>aResourceClass</code>.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static Resource produceResource(Class<? extends Resource> aResourceClass, ResourceSpecifier aSpecifier,
ResourceManager aResourceManager, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
// add ResourceManager to aAdditionalParams map
if (aResourceManager != null) {
if (aAdditionalParams == null) {
aAdditionalParams = new HashMap<String, Object>();
}
aAdditionalParams.put(Resource.PARAM_RESOURCE_MANAGER, aResourceManager);
}
return produceResource(aResourceClass, aSpecifier, aAdditionalParams);
}
/**
* Called if AE initialization succeeds. Sets the AE state to Ready and time
* it took to initialize the AE.
*
* @param ae
* @param initStartTime
*/
private static void updateAeState(AnalysisEngine ae, long initStartTime) {
if ( ae.getManagementInterface() instanceof AnalysisEngineManagementImpl) {
((AnalysisEngineManagementImpl)ae.getManagementInterface()).setState(State.Ready);
((AnalysisEngineManagementImpl)ae.getManagementInterface()).
setInitializationTime( System.currentTimeMillis() - initStartTime);
}
}
/**
* Produces an {@link AnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
* <p>
* The AnalysisEngine returned from this method is not guaranteed to be able to process multiple
* simultaneous requests. See {@link #produceAnalysisEngine(ResourceSpecifier,int,int)} for more
* information.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>AnalysisEngine</code>.
*
* @return an <code>AnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static AnalysisEngine produceAnalysisEngine(ResourceSpecifier aSpecifier)
throws ResourceInitializationException {
AnalysisEngine ae = null;
// Fetch current time to compute initialization time
long initStartTime = System.currentTimeMillis();
ae = (AnalysisEngine) produceResource(AnalysisEngine.class, aSpecifier, null);
// initialization succeeded, update AE state and initialization time
updateAeState(ae,initStartTime);
return ae;
}
/**
* Produces an {@link AnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>AnalysisEngine</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. Valid parameter names are defined as constants on the
* {@link AnalysisEngine} interface. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return an <code>AnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static AnalysisEngine produceAnalysisEngine(ResourceSpecifier aSpecifier,
Map<String, Object> aAdditionalParams) throws ResourceInitializationException {
AnalysisEngine ae = null;
// Fetch current time to compute initialization time
long initStartTime = System.currentTimeMillis();
ae = (AnalysisEngine) produceResource(AnalysisEngine.class, aSpecifier, aAdditionalParams);
// initialization succeeded, update AE state and initialization time
updateAeState(ae,initStartTime);
return ae;
}
/**
* Produces an {@link AnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>AnalysisEngine</code>.
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this analysis engine. If not
* specified, the default one returned by {@link #newDefaultResourceManager()} will be
* used.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. Valid parameter names are defined as constants on the
* {@link AnalysisEngine} interface. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return an <code>AnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static AnalysisEngine produceAnalysisEngine(ResourceSpecifier aSpecifier,
ResourceManager aResourceManager, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
AnalysisEngine ae = null;
// Fetch current time to compute initialization time
long initStartTime = System.currentTimeMillis();
ae = (AnalysisEngine) produceResource(AnalysisEngine.class, aSpecifier, aResourceManager,
aAdditionalParams);
// initialization succeeded, update AE state and initialization time
updateAeState(ae,initStartTime);
return ae;
}
/**
* Produces an {@link AnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
* <p>
* This version of <code>produceAnalysisEngine</code> allows the convenient creation of
* AnalysisEngines that can handle multiple simultaneous requests. Using this method is equivalent
* to using {@link #produceAnalysisEngine(ResourceSpecifier,Map)} and including values for
* {@link AnalysisEngine#PARAM_NUM_SIMULTANEOUS_REQUESTS} and
* {@link AnalysisEngine#PARAM_TIMEOUT_PERIOD} in the parameter map.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>AnalysisEngine</code>.
* @param 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
* {@link AnalysisEngine#PARAM_NUM_SIMULTANEOUS_REQUESTS}.
* @param aTimeoutPeriod -
* when the number of simultaneous requests exceeds <code>aMaxSimultaneousReqeusts</code>,
* 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
* {@link AnalysisEngine#PARAM_TIMEOUT_PERIOD}.
*
* @return an <code>AnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static AnalysisEngine produceAnalysisEngine(ResourceSpecifier aSpecifier,
int aMaxSimultaneousRequests, int aTimeoutPeriod) throws ResourceInitializationException {
// add parameters to the aAdditionalParams map
Map<String, Object> aAdditionalParams = new HashMap<String, Object>();
aAdditionalParams.put(AnalysisEngine.PARAM_NUM_SIMULTANEOUS_REQUESTS, Integer.valueOf(
aMaxSimultaneousRequests));
aAdditionalParams.put(AnalysisEngine.PARAM_TIMEOUT_PERIOD, Integer.valueOf(aTimeoutPeriod));
AnalysisEngine ae = null;
// Fetch current time to compute initialization time
long initStartTime = System.currentTimeMillis();
ae = (AnalysisEngine) produceResource(AnalysisEngine.class, aSpecifier, aAdditionalParams);
// initialization succeeded, update AE state and initialization time
updateAeState(ae,initStartTime);
return ae;
}
/**
* Produces a {@link TextAnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
* <p>
* The TextAnalysisEngine returned from this method is not guaranteed to be able to process
* multiple simultaneous requests. See {@link #produceTAE(ResourceSpecifier,int,int)} for more
* information.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>TextAnalysisEngine</code>.
*
* @return a <code>TextAnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*
* @deprecated As of v2.0, {@link #produceAnalysisEngine(ResourceSpecifier)} should be used
* instead.
*/
@Deprecated
public static TextAnalysisEngine produceTAE(ResourceSpecifier aSpecifier)
throws ResourceInitializationException {
return (TextAnalysisEngine) produceResource(TextAnalysisEngine.class, aSpecifier, null);
}
/**
* Produces a {@link TextAnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>TextAnalysisEngine</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. Valid parameter names are defined as constants on the
* {@link AnalysisEngine} interface. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>TextAnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*
* @deprecated As of v2.0, {@link #produceAnalysisEngine(ResourceSpecifier,Map)} should be used
* instead.
*/
@Deprecated
public static TextAnalysisEngine produceTAE(ResourceSpecifier aSpecifier, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return (TextAnalysisEngine) produceResource(TextAnalysisEngine.class, aSpecifier,
aAdditionalParams);
}
/**
* Produces an {@link TextAnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>TextAnalysisEngine</code>.
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this analysis engine. If not
* specified, the default one returned by {@link #newDefaultResourceManager()} will be
* used.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. Valid parameter names are defined as constants on the
* {@link AnalysisEngine} interface. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>TextAnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*
* @deprecated As of v2.0, {@link #produceAnalysisEngine(ResourceSpecifier,ResourceManager,Map)}
* should be used instead.
*/
@Deprecated
public static TextAnalysisEngine produceTAE(ResourceSpecifier aSpecifier,
ResourceManager aResourceManager, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return (TextAnalysisEngine) produceResource(TextAnalysisEngine.class, aSpecifier,
aResourceManager, aAdditionalParams);
}
/**
* Produces a {@link TextAnalysisEngine} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
* <p>
* This version of <code>produceTAE</code> allows the convenient creation of TAEs that can
* handle multiple simultaneous requests. Using this method is equivalent to using
* {@link #produceTAE(ResourceSpecifier,Map)} and including values for
* {@link AnalysisEngine#PARAM_NUM_SIMULTANEOUS_REQUESTS} and
* {@link AnalysisEngine#PARAM_TIMEOUT_PERIOD} in the parameter map.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>TextAnalysisEngine</code>.
* @param aMaxSimultaneousRequests
* the number of simultaneous requests that this TAE should be able to process. The value
* for this parameter should be chosen careful - see the JavaDocs for
* {@link AnalysisEngine#PARAM_NUM_SIMULTANEOUS_REQUESTS}.
* @param aTimeoutPeriod -
* when the number of simultaneous requests exceeds <code>aMaxSimultaneousReqeusts</code>,
* 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
* {@link AnalysisEngine#PARAM_TIMEOUT_PERIOD}.
*
* @return a <code>TextAnalysisEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*
* @deprecated As of v2.0, {@link #produceAnalysisEngine(ResourceSpecifier,int,int)} should be
* used instead.
*/
@Deprecated
public static TextAnalysisEngine produceTAE(ResourceSpecifier aSpecifier,
int aMaxSimultaneousRequests, int aTimeoutPeriod) throws ResourceInitializationException {
// add parameters to the aAdditionalParams map
Map<String, Object> aAdditionalParams = new HashMap<String, Object>();
aAdditionalParams.put(AnalysisEngine.PARAM_NUM_SIMULTANEOUS_REQUESTS, Integer.valueOf(
aMaxSimultaneousRequests));
aAdditionalParams.put(AnalysisEngine.PARAM_TIMEOUT_PERIOD, Integer.valueOf(aTimeoutPeriod));
return (TextAnalysisEngine) produceResource(TextAnalysisEngine.class, aSpecifier,
aAdditionalParams);
}
/**
* Produces a {@link CasConsumer} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CasConsumer</code>.
*
* @return a <code>CasConsumer</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CasConsumer produceCasConsumer(ResourceSpecifier aSpecifier)
throws ResourceInitializationException {
return (CasConsumer) produceResource(CasConsumer.class, aSpecifier, null);
}
/**
* Produces a {@link CasConsumer} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CasConsumer</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. For example this can be used to set performance-tuning
* settings as described in {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>CasConsumer</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CasConsumer produceCasConsumer(ResourceSpecifier aSpecifier, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return (CasConsumer) produceResource(CasConsumer.class, aSpecifier, aAdditionalParams);
}
/**
* Produces an {@link CasConsumer} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CasConsumer</code>.
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this CasConsumer. If not specified,
* the default one returned by {@link #newDefaultResourceManager()} will be used.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. Valid parameter names are defined as constants on the
* {@link CasConsumer} interface. For example this can be used to set performance-tuning
* settings as described in {@link #getDefaultPerformanceTuningProperties()}.
*
* @return an <code>CasConsumer</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CasConsumer produceCasConsumer(ResourceSpecifier aSpecifier,
ResourceManager aResourceManager, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return (CasConsumer) produceResource(CasConsumer.class, aSpecifier, aResourceManager,
aAdditionalParams);
}
/**
* Produces a {@link CollectionReader} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CollectionReader</code>.
*
* @return a <code>CollectionReader</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CollectionReader produceCollectionReader(ResourceSpecifier aSpecifier)
throws ResourceInitializationException {
return (CollectionReader) produceResource(CollectionReader.class, aSpecifier, null);
}
/**
* Produces a {@link CollectionReader} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CollectionReader</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. For example this can be used to set performance-tuning
* settings as described in {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>CollectionReader</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CollectionReader produceCollectionReader(ResourceSpecifier aSpecifier,
Map<String, Object> aAdditionalParams) throws ResourceInitializationException {
return (CollectionReader) produceResource(CollectionReader.class, aSpecifier, aAdditionalParams);
}
/**
* Produces an {@link CollectionReader} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CollectionReader</code>.
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this CollectionReader. If not
* specified, the default one returned by {@link #newDefaultResourceManager()} will be
* used.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. Valid parameter names are defined as constants on the
* {@link CollectionReader} interface. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return an <code>CollectionReader</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CollectionReader produceCollectionReader(ResourceSpecifier aSpecifier,
ResourceManager aResourceManager, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return (CollectionReader) produceResource(CollectionReader.class, aSpecifier, aResourceManager,
aAdditionalParams);
}
/**
* Produces a {@link CasInitializer} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CasInitializer</code>.
*
* @return a <code>CasInitializer</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*
* @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
* {@link org.apache.uima.examples.XmlDetagger} for an example.
*/
@Deprecated
public static CasInitializer produceCasInitializer(ResourceSpecifier aSpecifier)
throws ResourceInitializationException {
return (CasInitializer) produceResource(CasInitializer.class, aSpecifier, null);
}
/**
* Produces a {@link CasInitializer} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CasInitializer</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. For example this can be used to set performance-tuning
* settings as described in {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>CasInitializer</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CasInitializer produceCasInitializer(ResourceSpecifier aSpecifier,
Map<String, Object> aAdditionalParams) throws ResourceInitializationException {
return (CasInitializer) produceResource(CasInitializer.class, aSpecifier, aAdditionalParams);
}
/**
* Produces an {@link CasInitializer} instance from a <code>ResourceSpecifier</code>. The
* <code>ResourceSpecifier</code> may either specify how to construct a new instance or how to
* locate an existing instance.
*
* @param aSpecifier
* an object that specifies how to acquire an instance of a <code>Resource</code>.
* This must specify a subclass of <code>CasInitializer</code>.
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this CasInitializer. If not
* specified, the default one returned by {@link #newDefaultResourceManager()} will be
* used.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link Resource#initialize(ResourceSpecifier,Map)} method. May be <code>null</code>
* if there are no parameters. Valid parameter names are defined as constants on the
* {@link CasInitializer} interface. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return an <code>CasInitializer</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the resource.
*/
public static CasInitializer produceCasInitializer(ResourceSpecifier aSpecifier,
ResourceManager aResourceManager, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return (CasInitializer) produceResource(CasInitializer.class, aSpecifier, aResourceManager,
aAdditionalParams);
}
/**
* Produces a {@link CollectionProcessingEngine} instance from a <code>cpeDescription</code>.
*
* @param aCpeDescription
* an object that specifies how to create an instance of a
* <code>CollectionProcessingEngine</code>.
*
* @return a <code>CollectionProcessingEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the CPE.
*/
public static CollectionProcessingEngine produceCollectionProcessingEngine(
CpeDescription aCpeDescription) throws ResourceInitializationException {
return getInstance()._produceCollectionProcessingEngine(aCpeDescription, null);
}
/**
* Produces a {@link CollectionProcessingEngine} instance from a <code>cpeDescription</code>.
*
* @param aCpeDescription
* an object that specifies how to create an instance of a
* <code>CollectionProcessingEngine</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link CollectionProcessingEngine#initialize(CpeDescription,Map)} method. May be
* <code>null</code> if there are no parameters. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>CollectionProcessingEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the CPE.
*/
public static CollectionProcessingEngine produceCollectionProcessingEngine(
CpeDescription aCpeDescription, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
return getInstance()._produceCollectionProcessingEngine(aCpeDescription, aAdditionalParams);
}
/**
* Produces a {@link CollectionProcessingEngine} instance from a <code>cpeDescription</code>.
*
* @param aCpeDescription
* an object that specifies how to create an instance of a
* <code>CollectionProcessingEngine</code>.
* @param aResourceManager
* the <code>ResourceManager</code> to be used by this CollectionProcessingEngine. If
* not specified, the default one returned by {@link #newDefaultResourceManager()} will
* be used.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link CollectionProcessingEngine#initialize(CpeDescription,Map)} method. May be
* <code>null</code> if there are no parameters. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>CollectionProcessingEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the CPE.
*/
public static CollectionProcessingEngine produceCollectionProcessingEngine(
CpeDescription aCpeDescription, ResourceManager aResourceManager, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException {
if (aResourceManager != null) {
if (aAdditionalParams == null) {
aAdditionalParams = new HashMap<String, Object>();
}
aAdditionalParams.put(Resource.PARAM_RESOURCE_MANAGER, aResourceManager);
}
return getInstance()._produceCollectionProcessingEngine(aCpeDescription, aAdditionalParams);
}
/**
* Gets the {@link org.apache.uima.util.Logger} used by the UIMA framework. An application won't
* generally write to this logger, although nothing is stopping it from doing so.
* <p>
* 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.
*
* @return the default Logger used by UIMA components
*/
public static Logger getLogger() {
return getInstance()._getLogger();
}
/**
* Gets the {@link org.apache.uima.util.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.
* <p>
* 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.
*
* @param component
* the Class for a component, for example an Annotator or CAS Consumer
*
* @return the Logger used by the specified component class
*/
public static Logger getLogger(Class<?> component) {
return getInstance()._getLogger(component);
}
/**
* Creates a new {@link org.apache.uima.util.Logger}, which can be passed for example to the
* {@link AnalysisEngine#setLogger(Logger)} method in order to have separate Analysis Engine
* instances used separate loggers.
*
* @return a new Logger instance
*
* @see #getLogger()
*/
public static Logger newLogger() {
return getInstance()._newLogger();
}
/**
* Creates a new {@link org.apache.uima.util.UimaTimer}, which is used to collect performance
* statistics for UIMA components.
*
* @return a new Timer instance
*/
public static UimaTimer newTimer() {
return getInstance()._newTimer();
}
/**
* Gets a new instance of the default {@link ResourceManager} used by this implementation. An
* application can configure this ResourceManager and then pass it to the
* {@link #produceAnalysisEngine(ResourceSpecifier,ResourceManager,Map)} method.
*
* @return a new <code>ResourceManager</code> to be used by the application.
*/
public static ResourceManager newDefaultResourceManager() {
return getInstance()._newDefaultResourceManager();
}
/**
* Gets a new instance of the default {@link org.apache.uima.resource.ResourceManagerPearWrapper} used by this implementation.
*
* @return a new <code>ResourceManagerPearWrapper</code> to be used by the application.
*/
public static ResourceManager newDefaultResourceManagerPearWrapper() {
return getInstance()._newDefaultResourceManagerPearWrapper();
}
/**
* Gets a new instance of the {@link ConfigurationManager} used by this implementation. This will
* be used by Resources to manage access to their configuration parameters.
*
* @return a new <code>ConfigurationManager</code> to be used by the application.
*/
public static ConfigurationManager newConfigurationManager() {
return getInstance()._newConfigurationManager();
}
/**
* Gets a new instance of a {@link UimaContext}. Applications do not generally need to call this
* method.
*
* @param aLogger
* the logger that will be returned by this UimaContext's {@link #getLogger()} method.
* @param aResourceManager
* the ResourceManager that will be used by this UimaContext to locate and access
* external resource.
* @param aConfigManager
* the ConfigurationManager that will be used by this UimaContext to manage Configuration
* Parameter settings.
*
* @return a new UIMA Context to be used by the application.
*/
public static UimaContextAdmin newUimaContext(Logger aLogger, ResourceManager aResourceManager,
ConfigurationManager aConfigManager) {
UimaContextAdmin context = getInstance()._newUimaContext();
context.initializeRoot(aLogger, aResourceManager, aConfigManager);
return context;
}
/**
* 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
* {@link #produceTAE(ResourceSpecifier,Map)} or
* {@link #produceCollectionProcessingEngine(CpeDescription,Map)} methods by putting it into the
* <code>aAdditionalParams</code> map under the key
* {@link Resource#PARAM_PERFORMANCE_TUNING_SETTINGS}. For example, the following code set the
* initial heap size allocated in the CAS to 100,000:
*
* <pre>
* Properties perfProps = UIMAFramework.getDefaultPerformanceTuningProperties();
* perfProps.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);
* </pre>
*
* <p>
* Valid keys for the {@link Properties} object returned by this method are specified as
* constants on this interface.
*
* @return 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.
*/
public static Properties getDefaultPerformanceTuningProperties() {
return getInstance()._getDefaultPerformanceTuningProperties();
}
/**
* Gets the <code>UIMAFramework</code> instance currently in use.
*
* @return the <code>UIMAFramework</code> instance currently in use
*/
protected static synchronized UIMAFramework getInstance() {
return mInstance;
}
/**
* To be implemented by subclasses; this should return the major version number of this
* implementation.
*
* @return the major version number
*/
protected abstract short _getMajorVersion();
/**
* To be implemented by subclasses; this should return the minor version number of this
* implementation.
*
* @return the minor version number
*/
protected abstract short _getMinorVersion();
/**
* 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 {@link #getInstance()} method can be used during initialization.
*
* @throws Exception
* if initialization fails
*/
protected abstract void _initialize() throws Exception;
/**
* To be implemented by subclasses; this should return the build revision number of this
* implementation.
*
* @return the build revision number
*/
protected abstract short _getBuildRevision();
/**
* To be implemented by subclasses; this should return a reference to the
* <code>ResourceFactory</code> used by this implementation, which must implement
* {@link CompositeResourceFactory}.
*
* @return the <code>ResourceFactory</code> to be used by the application
*/
protected abstract CompositeResourceFactory _getResourceFactory();
/**
* To be implemented by subclasses; this should return a reference to the
* <code>ResourceSpecifierFactory</code> used by this implementation.
*
* @return the <code>ResourceSpecifierFactory</code> to be used by the application.
*/
protected abstract ResourceSpecifierFactory _getResourceSpecifierFactory();
/**
* To be implemented by subclasses; this should return a reference to the UIMA {@link XMLParser}
* used by this implementation.
*
* @return the <code>XMLParser</code> to be used by the application.
*/
protected abstract XMLParser _getXMLParser();
/**
* To be implemented by subclasses; this should create a new instance of a class implementing
* {@link CollectionProcessingManager}.
*
* @param aResourceManager
* the ResourceManager to be used by the CPM
*
* @return a new <code>CollectionProcessingManager</code> to be used by the application.
*/
protected abstract CollectionProcessingManager _newCollectionProcessingManager(
ResourceManager aResourceManager);
/**
* To be implemented by subclasses; this should return a reference to the default UIMA
* {@link Logger} used by this implementation.
*
* @return the default <code>Logger</code> used by this implementation
*/
protected abstract Logger _getLogger();
/**
* To be implemented by subclasses; this should return a reference to the UIMA {@link Logger} of
* the specified source class.
*
* @return the <code>Logger</code> of the specified source class
*/
protected abstract Logger _getLogger(Class<?> component);
/**
* To be implemented by subclasses; this should return a new UIMA {@link Logger} instance.
*
* @return a new <code>Logger</code> instance
*/
protected abstract Logger _newLogger();
/**
* To be implemented by subclasses; this should return a new UIMA {@link UimaTimer} instance.
*
* @return a new <code>Timer</code> instance
*/
protected abstract UimaTimer _newTimer();
/**
* To be implemented by subclasses; this should return a new instance of the default
* {@link ResourceManager} used by this implementation.
*
* @return a new <code>ResourceManager</code> to be used by the application.
*/
protected abstract ResourceManager _newDefaultResourceManager();
/**
* To be implemented by subclasses; this should return a new instance of the default
* {@link org.apache.uima.resource.ResourceManagerPearWrapper} used by this implementation.
*
* @return a new <code>ResourceManagerPearWrapper</code> to be used by the application.
*/
protected abstract ResourceManager _newDefaultResourceManagerPearWrapper();
/**
* To be implemented by subclasses; this should return a new instance of the default
* {@link ConfigurationManager} used by this implementation.
*
* @return a new <code>ConfigurationManager</code> to be used by the application.
*/
protected abstract ConfigurationManager _newConfigurationManager();
/**
* To be implemented by subclasses; this should return a new instance of the default
* {@link UimaContextAdmin} used by this implementation.
*
* @return a new <code>UimaContextAdmin</code> to be used by the application.
*/
protected abstract UimaContextAdmin _newUimaContext();
/**
* To be implemented by subclasses; this should produce a {@link CollectionProcessingEngine}
* instance from a <code>cpeDescription</code>.
*
* @param aCpeDescription
* an object that specifies how to create an instance of a
* <code>CollectionProcessingEngine</code>.
* @param aAdditionalParams
* a Map containing additional parameters to pass to the
* {@link CollectionProcessingEngine#initialize(CpeDescription,Map)} method. May be
* <code>null</code> if there are no parameters. For example this can be used to set
* performance-tuning settings as described in
* {@link #getDefaultPerformanceTuningProperties()}.
*
* @return a <code>CollectionProcessingEngine</code> instance.
*
* @throws ResourceInitializationException
* if a failure occurred during production of the CPE.
*/
protected abstract CollectionProcessingEngine _produceCollectionProcessingEngine(
CpeDescription aCpeDescription, Map<String, Object> aAdditionalParams)
throws ResourceInitializationException;
static {
// intall framework implementation
String frameworkClassName = null;
try {
frameworkClassName = System.getProperty("uima.framework_impl");
} catch (SecurityException e) {
// can't access system properties
}
if (frameworkClassName == null) {
frameworkClassName = REF_IMPL_CLASS_NAME; // use default
}
try {
Class<?> implClass = Class.forName(frameworkClassName);
mInstance = (UIMAFramework) implClass.newInstance();
mInstance._initialize();
} catch (Exception e) {
// could not load reference implementation
throw new UIMA_IllegalStateException(UIMA_IllegalStateException.COULD_NOT_CREATE_FRAMEWORK,
new Object[] { frameworkClassName }, e);
}
}
}